From 6b54065633e69218ab12134fb6b1dc4e9ca964c0 Mon Sep 17 00:00:00 2001
From: Guilherme Rodrigues <gui@deco.cx>
Date: Sat, 14 Feb 2026 09:18:06 -0300
Subject: [PATCH 01/26] feat(01-01): define SITE_BINDING and create site-editor
 plugin skeleton

- Add SITE_BINDING with READ_FILE, PUT_FILE, LIST_FILES tool binders
- Export SITE_BINDING from @decocms/bindings and add ./site entry point
- Create mesh-plugin-site-editor package with server/client entry points
- Add shared.ts with PLUGIN_ID and PLUGIN_DESCRIPTION constants

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/bindings/package.json                |   1 +
 packages/bindings/src/index.ts                |  12 ++
 packages/bindings/src/well-known/site.ts      | 108 ++++++++++++++++++
 packages/mesh-plugin-site-editor/package.json |  31 +++++
 packages/mesh-plugin-site-editor/shared.ts    |   9 ++
 .../mesh-plugin-site-editor/tsconfig.json     |  12 ++
 6 files changed, 173 insertions(+)
 create mode 100644 packages/bindings/src/well-known/site.ts
 create mode 100644 packages/mesh-plugin-site-editor/package.json
 create mode 100644 packages/mesh-plugin-site-editor/shared.ts
 create mode 100644 packages/mesh-plugin-site-editor/tsconfig.json

diff --git a/packages/bindings/package.json b/packages/bindings/package.json
index 79386ff3ca..a4d5688308 100644
--- a/packages/bindings/package.json
+++ b/packages/bindings/package.json
@@ -22,6 +22,7 @@
     "./collections": "./src/well-known/collections.ts",
     "./llm": "./src/well-known/language-model.ts",
     "./object-storage": "./src/well-known/object-storage.ts",
+    "./site": "./src/well-known/site.ts",
     "./connection": "./src/core/connection.ts",
     "./client": "./src/core/client/index.ts",
     "./mcp": "./src/well-known/mcp.ts",
diff --git a/packages/bindings/src/index.ts b/packages/bindings/src/index.ts
index eee481f77b..67a79a4f58 100644
--- a/packages/bindings/src/index.ts
+++ b/packages/bindings/src/index.ts
@@ -102,6 +102,18 @@ export {
   type DeleteObjectsOutput,
 } from "./well-known/object-storage";
 
+// Re-export site binding types
+export {
+  SITE_BINDING,
+  type SiteBinding,
+  type ReadFileInput,
+  type ReadFileOutput,
+  type PutFileInput,
+  type PutFileOutput,
+  type ListFilesInput,
+  type ListFilesOutput,
+} from "./well-known/site";
+
 // Re-export workflow binding types
 export { WORKFLOWS_COLLECTION_BINDING } from "./well-known/workflow";
 
diff --git a/packages/bindings/src/well-known/site.ts b/packages/bindings/src/well-known/site.ts
new file mode 100644
index 0000000000..465a8c556c
--- /dev/null
+++ b/packages/bindings/src/well-known/site.ts
@@ -0,0 +1,108 @@
+/**
+ * Site Well-Known Binding
+ *
+ * Defines the interface for site file operations (read, write, list).
+ * Any MCP that implements this binding can provide file management
+ * for a site's pages, sections, and loaders.
+ *
+ * This binding includes:
+ * - READ_FILE: Read a file's content by path
+ * - PUT_FILE: Write content to a file by path
+ * - LIST_FILES: List files with optional prefix filtering
+ */
+
+import { z } from "zod";
+import type { Binder, ToolBinder } from "../core/binder";
+
+// ============================================================================
+// Tool Schemas
+// ============================================================================
+
+/**
+ * READ_FILE - Read a file's content by path
+ */
+const ReadFileInputSchema = z.object({
+  path: z.string().describe("File path relative to project root"),
+});
+
+const ReadFileOutputSchema = z.object({
+  content: z.string().describe("File content as UTF-8 string"),
+});
+
+export type ReadFileInput = z.infer<typeof ReadFileInputSchema>;
+export type ReadFileOutput = z.infer<typeof ReadFileOutputSchema>;
+
+/**
+ * PUT_FILE - Write content to a file by path
+ */
+const PutFileInputSchema = z.object({
+  path: z.string().describe("File path relative to project root"),
+  content: z.string().describe("File content as UTF-8 string"),
+});
+
+const PutFileOutputSchema = z.object({
+  success: z.boolean().describe("Whether the write succeeded"),
+});
+
+export type PutFileInput = z.infer<typeof PutFileInputSchema>;
+export type PutFileOutput = z.infer<typeof PutFileOutputSchema>;
+
+/**
+ * LIST_FILES - List files with optional prefix filtering
+ */
+const ListFilesInputSchema = z.object({
+  prefix: z
+    .string()
+    .optional()
+    .describe("Path prefix filter (e.g., '.deco/pages/')"),
+});
+
+const ListFilesOutputSchema = z.object({
+  files: z.array(
+    z.object({
+      path: z.string().describe("File path relative to project root"),
+      sizeInBytes: z.number().describe("File size"),
+      mtime: z.number().describe("Last modified timestamp (epoch ms)"),
+    }),
+  ),
+  count: z.number().describe("Total file count"),
+});
+
+export type ListFilesInput = z.infer<typeof ListFilesInputSchema>;
+export type ListFilesOutput = z.infer<typeof ListFilesOutputSchema>;
+
+// ============================================================================
+// Binding Definition
+// ============================================================================
+
+/**
+ * Site Binding
+ *
+ * Defines the interface for site file operations.
+ * Any MCP that implements this binding can be used with the Site Editor plugin
+ * to provide a CMS UI for managing pages, sections, and loaders.
+ *
+ * Required tools:
+ * - READ_FILE: Read a file's content
+ * - PUT_FILE: Write content to a file
+ * - LIST_FILES: List files with prefix filtering
+ */
+export const SITE_BINDING = [
+  {
+    name: "READ_FILE" as const,
+    inputSchema: ReadFileInputSchema,
+    outputSchema: ReadFileOutputSchema,
+  } satisfies ToolBinder<"READ_FILE", ReadFileInput, ReadFileOutput>,
+  {
+    name: "PUT_FILE" as const,
+    inputSchema: PutFileInputSchema,
+    outputSchema: PutFileOutputSchema,
+  } satisfies ToolBinder<"PUT_FILE", PutFileInput, PutFileOutput>,
+  {
+    name: "LIST_FILES" as const,
+    inputSchema: ListFilesInputSchema,
+    outputSchema: ListFilesOutputSchema,
+  } satisfies ToolBinder<"LIST_FILES", ListFilesInput, ListFilesOutput>,
+] as const satisfies Binder;
+
+export type SiteBinding = typeof SITE_BINDING;
diff --git a/packages/mesh-plugin-site-editor/package.json b/packages/mesh-plugin-site-editor/package.json
new file mode 100644
index 0000000000..1ca5216186
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/package.json
@@ -0,0 +1,31 @@
+{
+  "name": "mesh-plugin-site-editor",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Site editor plugin for Mesh - manage pages, sections, and loaders",
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "exports": {
+    "./server": "./server/index.ts",
+    "./client": "./client/index.tsx"
+  },
+  "dependencies": {
+    "@decocms/bindings": "workspace:*",
+    "@decocms/mesh-sdk": "workspace:*",
+    "@deco/ui": "workspace:*",
+    "@untitledui/icons": "^0.0.19",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.8.3"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": ">=5.0.0",
+    "@tanstack/react-router": ">=1.0.0",
+    "nanoid": ">=5.0.0",
+    "react": "^19.2.0"
+  }
+}
diff --git a/packages/mesh-plugin-site-editor/shared.ts b/packages/mesh-plugin-site-editor/shared.ts
new file mode 100644
index 0000000000..b247d58259
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/shared.ts
@@ -0,0 +1,9 @@
+/**
+ * Site Editor Plugin - Shared Constants
+ *
+ * Safe for importing in both server and client bundles.
+ */
+
+export const PLUGIN_ID = "site-editor";
+export const PLUGIN_DESCRIPTION =
+  "CMS for managing site pages, sections, and loaders";
diff --git a/packages/mesh-plugin-site-editor/tsconfig.json b/packages/mesh-plugin-site-editor/tsconfig.json
new file mode 100644
index 0000000000..88d880a5b3
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/tsconfig.json
@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": ".",
+    "declaration": true,
+    "declarationMap": true,
+    "jsx": "react-jsx"
+  },
+  "include": ["**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.test.tsx"]
+}

From a0e32de867b6175efe9b18f3285ad03eeb4cc04c Mon Sep 17 00:00:00 2001
From: Guilherme Rodrigues <gui@deco.cx>
Date: Sat, 14 Feb 2026 09:18:52 -0300
Subject: [PATCH 02/26] feat(01-02): add preview panel component and tunnel URL
 hook

- PreviewPanel renders iframe pointing to tunnel URL with sandbox attrs
- useTunnelUrl resolves preview URL from connection metadata
- Empty state shows instructions to run `deco link`
- Component accepts path prop for page-specific previews

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../client/components/preview-panel.tsx       | 61 +++++++++++++++++++
 .../client/lib/use-tunnel-url.ts              | 44 +++++++++++++
 2 files changed, 105 insertions(+)
 create mode 100644 packages/mesh-plugin-site-editor/client/components/preview-panel.tsx
 create mode 100644 packages/mesh-plugin-site-editor/client/lib/use-tunnel-url.ts

diff --git a/packages/mesh-plugin-site-editor/client/components/preview-panel.tsx b/packages/mesh-plugin-site-editor/client/components/preview-panel.tsx
new file mode 100644
index 0000000000..4fa3c70e53
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/components/preview-panel.tsx
@@ -0,0 +1,61 @@
+/**
+ * Preview Panel Component
+ *
+ * Renders a full-size iframe pointing to the user's running local dev server
+ * via the tunnel URL created by `deco link`. When no tunnel URL is available,
+ * shows a helpful empty state with instructions.
+ *
+ * This component fills its parent container (100% width and height).
+ * Responsive viewport toggles will be added in Phase 3 (EDIT-04).
+ */
+
+import { useTunnelUrl } from "../lib/use-tunnel-url";
+
+interface PreviewPanelProps {
+  /** Page path to preview (e.g., "/", "/about") */
+  path?: string;
+}
+
+export function PreviewPanel({ path = "/" }: PreviewPanelProps) {
+  const { url, isLoading } = useTunnelUrl();
+
+  if (isLoading) {
+    return (
+      <div className="flex items-center justify-center h-full">
+        <span className="text-sm text-muted-foreground">
+          Loading preview...
+        </span>
+      </div>
+    );
+  }
+
+  if (!url) {
+    return (
+      <div className="flex flex-col items-center justify-center h-full gap-4 text-muted-foreground">
+        <p className="text-lg font-medium">No preview available</p>
+        <p className="text-sm">
+          Start your dev server and run{" "}
+          <code className="px-1.5 py-0.5 bg-muted rounded text-xs font-mono">
+            deco link
+          </code>{" "}
+          to see a live preview
+        </p>
+      </div>
+    );
+  }
+
+  const previewUrl = path !== "/" ? `${url}${path}` : url;
+
+  return (
+    <div className="relative w-full h-full">
+      <iframe
+        src={previewUrl}
+        className="w-full h-full border-0"
+        sandbox="allow-scripts allow-same-origin allow-forms allow-popups"
+        title="Site preview"
+      />
+    </div>
+  );
+}
+
+export default PreviewPanel;
diff --git a/packages/mesh-plugin-site-editor/client/lib/use-tunnel-url.ts b/packages/mesh-plugin-site-editor/client/lib/use-tunnel-url.ts
new file mode 100644
index 0000000000..86548e02b4
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/lib/use-tunnel-url.ts
@@ -0,0 +1,44 @@
+/**
+ * Hook to resolve the tunnel URL for the site preview.
+ *
+ * The tunnel URL is how users see their running local dev server in the
+ * Mesh admin. They start their dev server locally, run `deco link` to
+ * create a tunnel, and this hook resolves the preview URL.
+ *
+ * For Phase 1, the tunnel URL is extracted from the connection's metadata.
+ * The connection metadata may contain a `previewUrl` field set during
+ * `deco link`, or we fall back to null (showing a placeholder).
+ */
+
+import { usePluginContext } from "@decocms/mesh-sdk/plugins";
+import { SITE_BINDING } from "@decocms/bindings";
+
+export interface UseTunnelUrlResult {
+  /** The resolved tunnel URL, or null if not available */
+  url: string | null;
+  /** Whether the URL is still being resolved */
+  isLoading: boolean;
+}
+
+/**
+ * Resolves the tunnel URL from the plugin context's connection metadata.
+ *
+ * The connection metadata may contain:
+ * - `previewUrl`: The URL to the running local dev server (set by `deco link`)
+ *
+ * Returns null when no tunnel URL is configured, which causes the
+ * PreviewPanel to show instructions for running `deco link`.
+ */
+export function useTunnelUrl(): UseTunnelUrlResult {
+  const { connection } = usePluginContext<typeof SITE_BINDING>();
+
+  // The preview URL lives in connection metadata, set by `deco link`.
+  // The metadata field is Record<string, unknown> | null on the connection entity.
+  const metadata = connection?.metadata;
+  const previewUrl =
+    metadata && typeof metadata.previewUrl === "string"
+      ? metadata.previewUrl
+      : null;
+
+  return { url: previewUrl, isLoading: false };
+}

From ffe3137a5449186a3903ad2133b04f8e9e6a8545 Mon Sep 17 00:00:00 2001
From: Guilherme Rodrigues <gui@deco.cx>
Date: Sat, 14 Feb 2026 09:20:20 -0300
Subject: [PATCH 03/26] feat(01-01): implement ServerPlugin, ClientPlugin, and
 register in Mesh

- Add ServerPlugin with empty tools array (tools added in plan 01-03)
- Add ClientPlugin with SITE_BINDING, sidebar groups (Pages, Sections, Loaders)
- Create plugin router with 4 routes (/, /pages/$pageId, /sections, /loaders)
- Add stub page components, header, and empty state
- Register server plugin in apps/mesh/src/server-plugins.ts
- Register client plugin in apps/mesh/src/web/plugins.ts

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 apps/mesh/src/server-plugins.ts               |   2 +
 apps/mesh/src/web/plugins.ts                  |   2 +
 .../client/components/loaders-list.tsx        |  17 +++
 .../client/components/pages-list.tsx          |  17 +++
 .../client/components/plugin-empty-state.tsx  |  20 ++++
 .../client/components/plugin-header.tsx       | 102 ++++++++++++++++++
 .../client/components/sections-list.tsx       |  17 +++
 .../mesh-plugin-site-editor/client/index.tsx  |  55 ++++++++++
 .../client/lib/router.ts                      |  41 +++++++
 .../mesh-plugin-site-editor/server/index.ts   |  18 ++++
 .../server/tools/index.ts                     |   9 ++
 11 files changed, 300 insertions(+)
 create mode 100644 packages/mesh-plugin-site-editor/client/components/loaders-list.tsx
 create mode 100644 packages/mesh-plugin-site-editor/client/components/pages-list.tsx
 create mode 100644 packages/mesh-plugin-site-editor/client/components/plugin-empty-state.tsx
 create mode 100644 packages/mesh-plugin-site-editor/client/components/plugin-header.tsx
 create mode 100644 packages/mesh-plugin-site-editor/client/components/sections-list.tsx
 create mode 100644 packages/mesh-plugin-site-editor/client/index.tsx
 create mode 100644 packages/mesh-plugin-site-editor/client/lib/router.ts
 create mode 100644 packages/mesh-plugin-site-editor/server/index.ts
 create mode 100644 packages/mesh-plugin-site-editor/server/tools/index.ts

diff --git a/apps/mesh/src/server-plugins.ts b/apps/mesh/src/server-plugins.ts
index 091664f5d4..6b2fe09e11 100644
--- a/apps/mesh/src/server-plugins.ts
+++ b/apps/mesh/src/server-plugins.ts
@@ -11,6 +11,7 @@
 import type { ServerPlugin } from "@decocms/bindings/server-plugin";
 import { serverPlugin as privateRegistryPlugin } from "mesh-plugin-private-registry/server";
 import { serverPlugin as userSandboxPlugin } from "mesh-plugin-user-sandbox/server";
+import { serverPlugin as siteEditorPlugin } from "mesh-plugin-site-editor/server";
 import { serverPlugin as workflowsPlugin } from "mesh-plugin-workflows/server";
 
 /**
@@ -21,4 +22,5 @@ export const serverPlugins: ServerPlugin[] = [
   userSandboxPlugin,
   privateRegistryPlugin,
   workflowsPlugin,
+  siteEditorPlugin,
 ];
diff --git a/apps/mesh/src/web/plugins.ts b/apps/mesh/src/web/plugins.ts
index 96516bd9ce..d9e1393126 100644
--- a/apps/mesh/src/web/plugins.ts
+++ b/apps/mesh/src/web/plugins.ts
@@ -3,6 +3,7 @@ import { objectStoragePlugin } from "mesh-plugin-object-storage";
 import { clientPlugin as privateRegistryPlugin } from "mesh-plugin-private-registry/client";
 import { reportsPlugin } from "mesh-plugin-reports";
 import { clientPlugin as userSandboxPlugin } from "mesh-plugin-user-sandbox/client";
+import { clientPlugin as siteEditorPlugin } from "mesh-plugin-site-editor/client";
 import { clientPlugin as workflowsPlugin } from "mesh-plugin-workflows/client";
 
 // Registered plugins
@@ -12,4 +13,5 @@ export const sourcePlugins: AnyClientPlugin[] = [
   userSandboxPlugin,
   privateRegistryPlugin,
   workflowsPlugin,
+  siteEditorPlugin,
 ];
diff --git a/packages/mesh-plugin-site-editor/client/components/loaders-list.tsx b/packages/mesh-plugin-site-editor/client/components/loaders-list.tsx
new file mode 100644
index 0000000000..0b8f85e229
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/components/loaders-list.tsx
@@ -0,0 +1,17 @@
+/**
+ * Loaders List Component
+ *
+ * Displays the list of loaders managed by the site editor.
+ * Full implementation will be added in later plans.
+ */
+
+export default function LoadersList() {
+  return (
+    <div className="flex flex-col items-center justify-center h-full p-8">
+      <h3 className="text-lg font-medium mb-2">Loaders</h3>
+      <p className="text-muted-foreground text-center max-w-md">
+        Loaders will appear here once file listing is implemented.
+      </p>
+    </div>
+  );
+}
diff --git a/packages/mesh-plugin-site-editor/client/components/pages-list.tsx b/packages/mesh-plugin-site-editor/client/components/pages-list.tsx
new file mode 100644
index 0000000000..4af5583e87
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/components/pages-list.tsx
@@ -0,0 +1,17 @@
+/**
+ * Pages List Component
+ *
+ * Displays the list of pages managed by the site editor.
+ * Full implementation will be added in plan 01-02.
+ */
+
+export default function PagesList() {
+  return (
+    <div className="flex flex-col items-center justify-center h-full p-8">
+      <h3 className="text-lg font-medium mb-2">Pages</h3>
+      <p className="text-muted-foreground text-center max-w-md">
+        Pages will appear here once file listing is implemented.
+      </p>
+    </div>
+  );
+}
diff --git a/packages/mesh-plugin-site-editor/client/components/plugin-empty-state.tsx b/packages/mesh-plugin-site-editor/client/components/plugin-empty-state.tsx
new file mode 100644
index 0000000000..182061c2a0
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/components/plugin-empty-state.tsx
@@ -0,0 +1,20 @@
+/**
+ * Plugin Empty State Component
+ *
+ * Shown when no site connections are available.
+ */
+
+import { File06 } from "@untitledui/icons";
+
+export default function PluginEmptyState() {
+  return (
+    <div className="flex flex-col items-center justify-center h-full p-8">
+      <File06 size={48} className="text-muted-foreground mb-4" />
+      <h3 className="text-lg font-medium mb-2">No site connected</h3>
+      <p className="text-muted-foreground text-center max-w-md">
+        Connect a local-fs MCP server to manage your site's pages, sections, and
+        loaders.
+      </p>
+    </div>
+  );
+}
diff --git a/packages/mesh-plugin-site-editor/client/components/plugin-header.tsx b/packages/mesh-plugin-site-editor/client/components/plugin-header.tsx
new file mode 100644
index 0000000000..4e139a30d6
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/components/plugin-header.tsx
@@ -0,0 +1,102 @@
+/**
+ * Plugin Header Component
+ *
+ * Connection selector for the site editor plugin.
+ * Uses native HTML elements to avoid type conflicts with UI package.
+ */
+
+import type { PluginRenderHeaderProps } from "@decocms/bindings/plugins";
+import { File06, ChevronDown, Check } from "@untitledui/icons";
+import { useState, useRef } from "react";
+
+/**
+ * Simple dropdown menu using native elements.
+ */
+function ConnectionSelector({
+  connections,
+  selectedConnectionId,
+  onConnectionChange,
+}: PluginRenderHeaderProps) {
+  const [isOpen, setIsOpen] = useState(false);
+  const dropdownRef = useRef<HTMLDivElement>(null);
+
+  const selectedConnection = connections.find(
+    (c) => c.id === selectedConnectionId,
+  );
+
+  // Close dropdown when clicking outside
+  const handleBlur = (e: React.FocusEvent) => {
+    if (!dropdownRef.current?.contains(e.relatedTarget as Node)) {
+      setIsOpen(false);
+    }
+  };
+
+  if (connections.length === 1) {
+    return (
+      <div className="flex items-center gap-2 text-sm text-muted-foreground">
+        {selectedConnection?.icon ? (
+          <img
+            src={selectedConnection.icon}
+            alt=""
+            className="size-4 rounded"
+          />
+        ) : (
+          <File06 size={16} />
+        )}
+        <span>{selectedConnection?.title || "Site"}</span>
+      </div>
+    );
+  }
+
+  return (
+    <div className="relative" ref={dropdownRef} onBlur={handleBlur}>
+      <button
+        type="button"
+        onClick={() => setIsOpen(!isOpen)}
+        className="inline-flex items-center gap-2 px-3 py-1.5 text-sm font-medium rounded-md border border-border bg-background hover:bg-accent transition-colors"
+      >
+        {selectedConnection?.icon ? (
+          <img
+            src={selectedConnection.icon}
+            alt=""
+            className="size-4 rounded"
+          />
+        ) : (
+          <File06 size={16} />
+        )}
+        <span>{selectedConnection?.title || "Select site"}</span>
+        <ChevronDown size={14} />
+      </button>
+
+      {isOpen && (
+        <div className="absolute left-0 top-full mt-1 z-50 min-w-48 rounded-md border border-border bg-popover p-1 shadow-md">
+          {connections.map((connection) => (
+            <button
+              key={connection.id}
+              type="button"
+              onClick={() => {
+                onConnectionChange(connection.id);
+                setIsOpen(false);
+              }}
+              className="flex items-center gap-2 w-full px-2 py-1.5 text-sm rounded-sm hover:bg-accent transition-colors"
+            >
+              {connection.icon ? (
+                <img src={connection.icon} alt="" className="size-4 rounded" />
+              ) : (
+                <File06 size={16} />
+              )}
+              <span className="flex-1 text-left">{connection.title}</span>
+              {connection.id === selectedConnectionId && (
+                <Check size={14} className="text-primary" />
+              )}
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default function PluginHeader(props: PluginRenderHeaderProps) {
+  return <ConnectionSelector {...props} />;
+}
diff --git a/packages/mesh-plugin-site-editor/client/components/sections-list.tsx b/packages/mesh-plugin-site-editor/client/components/sections-list.tsx
new file mode 100644
index 0000000000..f857c8776b
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/components/sections-list.tsx
@@ -0,0 +1,17 @@
+/**
+ * Sections List Component
+ *
+ * Displays the list of sections managed by the site editor.
+ * Full implementation will be added in later plans.
+ */
+
+export default function SectionsList() {
+  return (
+    <div className="flex flex-col items-center justify-center h-full p-8">
+      <h3 className="text-lg font-medium mb-2">Sections</h3>
+      <p className="text-muted-foreground text-center max-w-md">
+        Sections will appear here once file listing is implemented.
+      </p>
+    </div>
+  );
+}
diff --git a/packages/mesh-plugin-site-editor/client/index.tsx b/packages/mesh-plugin-site-editor/client/index.tsx
new file mode 100644
index 0000000000..2e8ec3be89
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/index.tsx
@@ -0,0 +1,55 @@
+/**
+ * Site Editor Plugin - Client Entry Point
+ *
+ * Provides the CMS UI for managing site pages, sections, and loaders.
+ * Uses the SITE_BINDING to filter compatible connections.
+ */
+
+import { SITE_BINDING } from "@decocms/bindings/site";
+import type { Plugin, PluginSetupContext } from "@decocms/bindings/plugins";
+import { File06, LayoutAlt03, Database01 } from "@untitledui/icons";
+import { lazy } from "react";
+import { siteEditorRouter } from "./lib/router";
+
+// Lazy load the header/empty state components that use UI dependencies
+const PluginHeader = lazy(() => import("./components/plugin-header"));
+const PluginEmptyState = lazy(() => import("./components/plugin-empty-state"));
+
+/**
+ * Site Editor Plugin Definition
+ */
+export const clientPlugin: Plugin<typeof SITE_BINDING> = {
+  id: "site-editor",
+  description: "CMS for managing site pages, sections, and loaders",
+  binding: SITE_BINDING,
+  renderHeader: (props) => <PluginHeader {...props} />,
+  renderEmptyState: () => <PluginEmptyState />,
+  setup: (context: PluginSetupContext) => {
+    const { registerSidebarGroup, registerPluginRoutes } = context;
+
+    // Register sidebar group with CMS items
+    registerSidebarGroup({
+      id: "site-editor",
+      label: "CMS",
+      items: [
+        {
+          icon: <File06 size={16} />,
+          label: "Pages",
+        },
+        {
+          icon: <LayoutAlt03 size={16} />,
+          label: "Sections",
+        },
+        {
+          icon: <Database01 size={16} />,
+          label: "Loaders",
+        },
+      ],
+      defaultExpanded: true,
+    });
+
+    // Create and register plugin routes using the typed router
+    const routes = siteEditorRouter.createRoutes(context);
+    registerPluginRoutes(routes);
+  },
+};
diff --git a/packages/mesh-plugin-site-editor/client/lib/router.ts b/packages/mesh-plugin-site-editor/client/lib/router.ts
new file mode 100644
index 0000000000..4b1c17e111
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/lib/router.ts
@@ -0,0 +1,41 @@
+/**
+ * Site Editor Plugin Router
+ *
+ * Provides typed routing utilities for the site editor plugin.
+ * Uses createPluginRouter to get typed useSearch, useNavigate, etc.
+ */
+
+import { createPluginRouter } from "@decocms/bindings/plugins";
+
+/**
+ * Plugin router with typed hooks for navigation and search params.
+ */
+export const siteEditorRouter = createPluginRouter((ctx) => {
+  const { createRoute, lazyRouteComponent } = ctx.routing;
+
+  const pagesRoute = createRoute({
+    getParentRoute: () => ctx.parentRoute,
+    path: "/",
+    component: lazyRouteComponent(() => import("../components/pages-list")),
+  });
+
+  const pageEditorRoute = createRoute({
+    getParentRoute: () => ctx.parentRoute,
+    path: "/pages/$pageId",
+    component: lazyRouteComponent(() => import("../components/pages-list")),
+  });
+
+  const sectionsRoute = createRoute({
+    getParentRoute: () => ctx.parentRoute,
+    path: "/sections",
+    component: lazyRouteComponent(() => import("../components/sections-list")),
+  });
+
+  const loadersRoute = createRoute({
+    getParentRoute: () => ctx.parentRoute,
+    path: "/loaders",
+    component: lazyRouteComponent(() => import("../components/loaders-list")),
+  });
+
+  return [pagesRoute, pageEditorRoute, sectionsRoute, loadersRoute];
+});
diff --git a/packages/mesh-plugin-site-editor/server/index.ts b/packages/mesh-plugin-site-editor/server/index.ts
new file mode 100644
index 0000000000..0275b4651f
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/server/index.ts
@@ -0,0 +1,18 @@
+/**
+ * Site Editor Plugin - Server Entry Point
+ *
+ * Provides site file management tools (pages, sections, loaders).
+ * Tools have access to the mesh database (via Kysely) and MCP proxy.
+ */
+
+import type { ServerPlugin } from "@decocms/bindings/server-plugin";
+import { PLUGIN_ID, PLUGIN_DESCRIPTION } from "../shared";
+import { tools } from "./tools";
+
+export const serverPlugin: ServerPlugin = {
+  id: PLUGIN_ID,
+  description: PLUGIN_DESCRIPTION,
+
+  // MCP tools (added in plan 01-03)
+  tools,
+};
diff --git a/packages/mesh-plugin-site-editor/server/tools/index.ts b/packages/mesh-plugin-site-editor/server/tools/index.ts
new file mode 100644
index 0000000000..1d815bf8cd
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/server/tools/index.ts
@@ -0,0 +1,9 @@
+/**
+ * Site Editor Server Tools
+ *
+ * Page CRUD tools will be added in plan 01-03.
+ */
+
+import type { ServerPluginToolDefinition } from "@decocms/bindings/server-plugin";
+
+export const tools: ServerPluginToolDefinition[] = [];

From 94ec844c89eeef3c0c2f87d632f76a0576bdfadf Mon Sep 17 00:00:00 2001
From: Guilherme Rodrigues <gui@deco.cx>
Date: Sat, 14 Feb 2026 09:29:52 -0300
Subject: [PATCH 04/26] feat(01-03): implement five page CRUD server tools

- CMS_PAGE_LIST: lists pages from .deco/pages/ via LIST_FILES + READ_FILE
- CMS_PAGE_GET: reads single page by ID from .deco/pages/{id}.json
- CMS_PAGE_CREATE: creates page with nanoid ID, writes via PUT_FILE
- CMS_PAGE_UPDATE: reads existing page, merges fields, writes back
- CMS_PAGE_DELETE: tries DELETE_FILE, falls back to tombstone JSON
- All tools use try/finally with proxy.close?.() to prevent leaks

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../server/tools/index.ts                     | 15 ++-
 .../server/tools/page-create.ts               | 75 ++++++++++++++
 .../server/tools/page-delete.ts               | 69 +++++++++++++
 .../server/tools/page-get.ts                  | 68 +++++++++++++
 .../server/tools/page-list.ts                 | 99 +++++++++++++++++++
 .../server/tools/page-update.ts               | 89 +++++++++++++++++
 6 files changed, 413 insertions(+), 2 deletions(-)
 create mode 100644 packages/mesh-plugin-site-editor/server/tools/page-create.ts
 create mode 100644 packages/mesh-plugin-site-editor/server/tools/page-delete.ts
 create mode 100644 packages/mesh-plugin-site-editor/server/tools/page-get.ts
 create mode 100644 packages/mesh-plugin-site-editor/server/tools/page-list.ts
 create mode 100644 packages/mesh-plugin-site-editor/server/tools/page-update.ts

diff --git a/packages/mesh-plugin-site-editor/server/tools/index.ts b/packages/mesh-plugin-site-editor/server/tools/index.ts
index 1d815bf8cd..3a8f452cb6 100644
--- a/packages/mesh-plugin-site-editor/server/tools/index.ts
+++ b/packages/mesh-plugin-site-editor/server/tools/index.ts
@@ -1,9 +1,20 @@
 /**
  * Site Editor Server Tools
  *
- * Page CRUD tools will be added in plan 01-03.
+ * Page CRUD tools for managing CMS pages stored in .deco/pages/.
  */
 
 import type { ServerPluginToolDefinition } from "@decocms/bindings/server-plugin";
+import { PAGE_LIST } from "./page-list";
+import { PAGE_GET } from "./page-get";
+import { PAGE_CREATE } from "./page-create";
+import { PAGE_UPDATE } from "./page-update";
+import { PAGE_DELETE } from "./page-delete";
 
-export const tools: ServerPluginToolDefinition[] = [];
+export const tools: ServerPluginToolDefinition[] = [
+  PAGE_LIST,
+  PAGE_GET,
+  PAGE_CREATE,
+  PAGE_UPDATE,
+  PAGE_DELETE,
+];
diff --git a/packages/mesh-plugin-site-editor/server/tools/page-create.ts b/packages/mesh-plugin-site-editor/server/tools/page-create.ts
new file mode 100644
index 0000000000..4fa913b143
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/server/tools/page-create.ts
@@ -0,0 +1,75 @@
+/**
+ * CMS_PAGE_CREATE Tool
+ *
+ * Creates a new page as a JSON file in .deco/pages/{id}.json via MCP.
+ * Generates a unique ID with nanoid prefixed by "page_".
+ */
+
+import { z } from "zod";
+import { nanoid } from "nanoid";
+import type { ServerPluginToolDefinition } from "@decocms/bindings/server-plugin";
+
+const PageSchema = z.object({
+  id: z.string(),
+  path: z.string(),
+  title: z.string(),
+  blocks: z.array(z.unknown()),
+  metadata: z.object({
+    description: z.string(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+  }),
+});
+
+export const PAGE_CREATE: ServerPluginToolDefinition = {
+  name: "CMS_PAGE_CREATE",
+  description: "Create a new CMS page with title and path.",
+  inputSchema: z.object({
+    connectionId: z.string().describe("MCP connection ID for the site"),
+    title: z.string().describe("Page title"),
+    path: z.string().describe("URL path (e.g., /, /about)"),
+  }),
+  outputSchema: z.object({
+    page: PageSchema,
+  }),
+
+  handler: async (input, ctx) => {
+    const { connectionId, title, path } = input as {
+      connectionId: string;
+      title: string;
+      path: string;
+    };
+    const proxy = await ctx.createMCPProxy(connectionId);
+
+    try {
+      const id = `page_${nanoid(8)}`;
+      const now = new Date().toISOString();
+
+      const page = {
+        id,
+        path,
+        title,
+        blocks: [],
+        metadata: {
+          description: "",
+          createdAt: now,
+          updatedAt: now,
+        },
+      };
+
+      const content = JSON.stringify(page, null, 2);
+
+      await proxy.callTool({
+        name: "PUT_FILE",
+        arguments: {
+          path: `.deco/pages/${id}.json`,
+          content,
+        },
+      });
+
+      return { page };
+    } finally {
+      await proxy.close?.();
+    }
+  },
+};
diff --git a/packages/mesh-plugin-site-editor/server/tools/page-delete.ts b/packages/mesh-plugin-site-editor/server/tools/page-delete.ts
new file mode 100644
index 0000000000..f182f91527
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/server/tools/page-delete.ts
@@ -0,0 +1,69 @@
+/**
+ * CMS_PAGE_DELETE Tool
+ *
+ * Deletes a page by ID. Attempts to call DELETE_FILE on the MCP proxy.
+ * If DELETE_FILE is not available, writes a tombstone JSON as fallback.
+ *
+ * Phase 1 limitation: The SITE_BINDING only defines READ_FILE, PUT_FILE,
+ * LIST_FILES. DELETE_FILE may or may not be available on the underlying
+ * MCP server. The tombstone fallback ensures delete always "works" even
+ * when the server doesn't support file deletion.
+ */
+
+import { z } from "zod";
+import type { ServerPluginToolDefinition } from "@decocms/bindings/server-plugin";
+
+export const PAGE_DELETE: ServerPluginToolDefinition = {
+  name: "CMS_PAGE_DELETE",
+  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({
+    success: z.boolean(),
+  }),
+
+  handler: async (input, ctx) => {
+    const { connectionId, pageId } = input as {
+      connectionId: string;
+      pageId: string;
+    };
+    const proxy = await ctx.createMCPProxy(connectionId);
+
+    try {
+      const filePath = `.deco/pages/${pageId}.json`;
+
+      // Try DELETE_FILE first (may be available even if not in the binding)
+      try {
+        const result = await proxy.callTool({
+          name: "DELETE_FILE",
+          arguments: { path: filePath },
+        });
+
+        if (!result.isError) {
+          return { success: true };
+        }
+      } catch {
+        // DELETE_FILE not available, fall through to tombstone
+      }
+
+      // Fallback: write a tombstone file
+      await proxy.callTool({
+        name: "PUT_FILE",
+        arguments: {
+          path: filePath,
+          content: JSON.stringify(
+            { deleted: true, deletedAt: new Date().toISOString() },
+            null,
+            2,
+          ),
+        },
+      });
+
+      return { success: true };
+    } finally {
+      await proxy.close?.();
+    }
+  },
+};
diff --git a/packages/mesh-plugin-site-editor/server/tools/page-get.ts b/packages/mesh-plugin-site-editor/server/tools/page-get.ts
new file mode 100644
index 0000000000..8b7425396d
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/server/tools/page-get.ts
@@ -0,0 +1,68 @@
+/**
+ * CMS_PAGE_GET Tool
+ *
+ * Reads a single page by ID from .deco/pages/{pageId}.json via MCP.
+ */
+
+import { z } from "zod";
+import type { ServerPluginToolDefinition } from "@decocms/bindings/server-plugin";
+
+const PageSchema = z.object({
+  id: z.string(),
+  path: z.string(),
+  title: z.string(),
+  blocks: z.array(z.unknown()),
+  metadata: z.object({
+    description: z.string(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+  }),
+});
+
+export const PAGE_GET: ServerPluginToolDefinition = {
+  name: "CMS_PAGE_GET",
+  description: "Get a single CMS page by ID, including all fields.",
+  inputSchema: z.object({
+    connectionId: z.string().describe("MCP connection ID for the site"),
+    pageId: z.string().describe("Page ID (e.g., page_V1StGXR8)"),
+  }),
+  outputSchema: z.object({
+    page: PageSchema.nullable(),
+  }),
+
+  handler: async (input, ctx) => {
+    const { connectionId, pageId } = input as {
+      connectionId: string;
+      pageId: string;
+    };
+    const proxy = await ctx.createMCPProxy(connectionId);
+
+    try {
+      const readResult = await proxy.callTool({
+        name: "READ_FILE",
+        arguments: { path: `.deco/pages/${pageId}.json` },
+      });
+
+      if (readResult.isError) {
+        return { page: null };
+      }
+
+      const content = readResult.content?.[0]?.text;
+      if (!content) {
+        return { page: null };
+      }
+
+      try {
+        const page = JSON.parse(content);
+        if (page.deleted) {
+          return { page: null };
+        }
+        return { page };
+      } catch {
+        return { page: null };
+      }
+    } finally {
+      await proxy.close?.();
+    }
+  },
+};
diff --git a/packages/mesh-plugin-site-editor/server/tools/page-list.ts b/packages/mesh-plugin-site-editor/server/tools/page-list.ts
new file mode 100644
index 0000000000..98db784f45
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/server/tools/page-list.ts
@@ -0,0 +1,99 @@
+/**
+ * CMS_PAGE_LIST Tool
+ *
+ * Lists all pages stored in .deco/pages/ via MCP file operations.
+ * For each JSON file found, reads its content to extract page metadata.
+ */
+
+import { z } from "zod";
+import type { ServerPluginToolDefinition } from "@decocms/bindings/server-plugin";
+
+const PageSummarySchema = z.object({
+  id: z.string(),
+  path: z.string(),
+  title: z.string(),
+  updatedAt: z.string(),
+});
+
+export const PAGE_LIST: ServerPluginToolDefinition = {
+  name: "CMS_PAGE_LIST",
+  description:
+    "List all CMS pages with their metadata (id, path, title, updatedAt).",
+  inputSchema: z.object({
+    connectionId: z.string().describe("MCP connection ID for the site"),
+  }),
+  outputSchema: z.object({
+    pages: z.array(PageSummarySchema),
+  }),
+
+  handler: async (input, ctx) => {
+    const { connectionId } = input as { connectionId: string };
+    const proxy = await ctx.createMCPProxy(connectionId);
+
+    try {
+      // List files under .deco/pages/
+      const listResult = await proxy.callTool({
+        name: "LIST_FILES",
+        arguments: { prefix: ".deco/pages/" },
+      });
+
+      const listContent = listResult.content?.[0]?.text;
+      if (!listContent) {
+        return { pages: [] };
+      }
+
+      let fileList: { files: Array<{ path: string }>; count: number };
+      try {
+        fileList = JSON.parse(listContent);
+      } catch {
+        return { pages: [] };
+      }
+
+      if (!fileList.files || fileList.files.length === 0) {
+        return { pages: [] };
+      }
+
+      // Read each .json file to get page metadata
+      const pages: Array<{
+        id: string;
+        path: string;
+        title: string;
+        updatedAt: string;
+      }> = [];
+
+      for (const file of fileList.files) {
+        if (!file.path.endsWith(".json")) continue;
+
+        try {
+          const readResult = await proxy.callTool({
+            name: "READ_FILE",
+            arguments: { path: file.path },
+          });
+
+          const content = readResult.content?.[0]?.text;
+          if (!content) continue;
+
+          const page = JSON.parse(content);
+          if (page.deleted) continue; // Skip tombstoned pages
+
+          pages.push({
+            id: page.id,
+            path: page.path,
+            title: page.title,
+            updatedAt: page.metadata?.updatedAt ?? "",
+          });
+        } catch {
+          // Skip files that can't be read or parsed
+          continue;
+        }
+      }
+
+      // Sort by updatedAt descending
+      pages.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+
+      return { pages };
+    } finally {
+      await proxy.close?.();
+    }
+  },
+};
diff --git a/packages/mesh-plugin-site-editor/server/tools/page-update.ts b/packages/mesh-plugin-site-editor/server/tools/page-update.ts
new file mode 100644
index 0000000000..89163920d8
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/server/tools/page-update.ts
@@ -0,0 +1,89 @@
+/**
+ * CMS_PAGE_UPDATE Tool
+ *
+ * Updates an existing page by reading, merging fields, and writing back.
+ * Only overwrites fields that are present in input.
+ */
+
+import { z } from "zod";
+import type { ServerPluginToolDefinition } from "@decocms/bindings/server-plugin";
+
+const PageSchema = z.object({
+  id: z.string(),
+  path: z.string(),
+  title: z.string(),
+  blocks: z.array(z.unknown()),
+  metadata: z.object({
+    description: z.string(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+  }),
+});
+
+export const PAGE_UPDATE: ServerPluginToolDefinition = {
+  name: "CMS_PAGE_UPDATE",
+  description:
+    "Update an existing CMS page. Only provided fields are overwritten.",
+  inputSchema: z.object({
+    connectionId: z.string().describe("MCP connection ID for the site"),
+    pageId: z.string().describe("Page ID to update"),
+    title: z.string().optional().describe("New page title"),
+    path: z.string().optional().describe("New URL path"),
+    blocks: z.array(z.unknown()).optional().describe("Page content blocks"),
+  }),
+  outputSchema: z.object({
+    page: PageSchema,
+  }),
+
+  handler: async (input, ctx) => {
+    const { connectionId, pageId, title, path, blocks } = input as {
+      connectionId: string;
+      pageId: string;
+      title?: string;
+      path?: string;
+      blocks?: unknown[];
+    };
+    const proxy = await ctx.createMCPProxy(connectionId);
+
+    try {
+      // Read existing page
+      const readResult = await proxy.callTool({
+        name: "READ_FILE",
+        arguments: { path: `.deco/pages/${pageId}.json` },
+      });
+
+      const content = readResult.content?.[0]?.text;
+      if (!content) {
+        throw new Error(`Page ${pageId} not found`);
+      }
+
+      const page = JSON.parse(content);
+
+      // Merge provided fields
+      if (title !== undefined) page.title = title;
+      if (path !== undefined) page.path = path;
+      if (blocks !== undefined) page.blocks = blocks;
+
+      // Update timestamp
+      page.metadata = {
+        ...page.metadata,
+        updatedAt: new Date().toISOString(),
+      };
+
+      // Write back
+      const updatedContent = JSON.stringify(page, null, 2);
+
+      await proxy.callTool({
+        name: "PUT_FILE",
+        arguments: {
+          path: `.deco/pages/${pageId}.json`,
+          content: updatedContent,
+        },
+      });
+
+      return { page };
+    } finally {
+      await proxy.close?.();
+    }
+  },
+};

From 4dae337c4492fd09a4f115a7dd3c813beb6d6754 Mon Sep 17 00:00:00 2001
From: Guilherme Rodrigues <gui@deco.cx>
Date: Sat, 14 Feb 2026 09:35:19 -0300
Subject: [PATCH 05/26] feat(01-03): implement pages list and page editor UI
 components

- pages-list.tsx: table view with create dialog, delete action, navigation
- page-editor.tsx: form for title/path with save, breadcrumb, metadata display
- page-api.ts: client-side CRUD helpers using SITE_BINDING tools directly
- query-keys.ts: structured React Query keys for page caching
- router.ts: updated /pages/$pageId route to point to page-editor component

Deviation: Client calls SITE_BINDING tools (READ_FILE, PUT_FILE, LIST_FILES)
directly via page-api helpers instead of CMS_PAGE_* server tools, because
the plugin toolCaller is connected to the site MCP (not the SELF MCP where
server tools live). Server tools still exist for AI agent access via SELF MCP.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../client/components/page-editor.tsx         | 232 +++++++++++++++
 .../client/components/pages-list.tsx          | 265 +++++++++++++++++-
 .../client/lib/page-api.ts                    | 178 ++++++++++++
 .../client/lib/query-keys.ts                  |  12 +
 .../client/lib/router.ts                      |   2 +-
 5 files changed, 681 insertions(+), 8 deletions(-)
 create mode 100644 packages/mesh-plugin-site-editor/client/components/page-editor.tsx
 create mode 100644 packages/mesh-plugin-site-editor/client/lib/page-api.ts
 create mode 100644 packages/mesh-plugin-site-editor/client/lib/query-keys.ts

diff --git a/packages/mesh-plugin-site-editor/client/components/page-editor.tsx b/packages/mesh-plugin-site-editor/client/components/page-editor.tsx
new file mode 100644
index 0000000000..1f70cb79fd
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/components/page-editor.tsx
@@ -0,0 +1,232 @@
+/**
+ * Page Editor Component
+ *
+ * Form for editing page metadata (title, path).
+ * Blocks editing is deferred to Phase 3.
+ * Uses SITE_BINDING tools (READ_FILE, PUT_FILE) via page-api helpers.
+ */
+
+import { useRef, useState } from "react";
+import { SITE_BINDING } from "@decocms/bindings/site";
+import { usePluginContext } from "@decocms/mesh-sdk/plugins";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { Button } from "@deco/ui/components/button.tsx";
+import { Input } from "@deco/ui/components/input.tsx";
+import { Label } from "@deco/ui/components/label.tsx";
+import { ArrowLeft, Save01, Loading01, AlertCircle } from "@untitledui/icons";
+import { toast } from "sonner";
+import { queryKeys } from "../lib/query-keys";
+import { siteEditorRouter } from "../lib/router";
+import { getPage, updatePage } from "../lib/page-api";
+
+function formatTimestamp(dateStr: string): string {
+  if (!dateStr) return "-";
+  try {
+    return new Date(dateStr).toLocaleString(undefined, {
+      year: "numeric",
+      month: "short",
+      day: "numeric",
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+    });
+  } catch {
+    return dateStr;
+  }
+}
+
+export default function PageEditor() {
+  const { toolCaller, connectionId } = usePluginContext<typeof SITE_BINDING>();
+  const queryClient = useQueryClient();
+  const navigate = siteEditorRouter.useNavigate();
+  const { pageId } = siteEditorRouter.useParams({ from: "/pages/$pageId" });
+
+  const [title, setTitle] = useState("");
+  const [path, setPath] = useState("");
+  const [isDirty, setIsDirty] = useState(false);
+  const lastSyncedPageId = useRef<string | null>(null);
+
+  // Fetch page
+  const {
+    data: page,
+    isLoading,
+    error,
+  } = useQuery({
+    queryKey: queryKeys.pages.detail(connectionId, pageId),
+    queryFn: () => getPage(toolCaller, pageId),
+  });
+
+  // Sync form state when page data loads (replaces useEffect)
+  if (page && lastSyncedPageId.current !== page.metadata.updatedAt) {
+    lastSyncedPageId.current = page.metadata.updatedAt;
+    setTitle(page.title);
+    setPath(page.path);
+    setIsDirty(false);
+  }
+
+  // Save mutation
+  const saveMutation = useMutation({
+    mutationFn: () => updatePage(toolCaller, pageId, { title, path }),
+    onSuccess: (updatedPage) => {
+      toast.success("Page saved");
+      setIsDirty(false);
+      queryClient.setQueryData(
+        queryKeys.pages.detail(connectionId, pageId),
+        updatedPage,
+      );
+      queryClient.invalidateQueries({
+        queryKey: queryKeys.pages.all(connectionId),
+      });
+    },
+    onError: (err) => {
+      toast.error(
+        `Failed to save: ${err instanceof Error ? err.message : "Unknown error"}`,
+      );
+    },
+  });
+
+  const handleTitleChange = (value: string) => {
+    setTitle(value);
+    setIsDirty(true);
+  };
+
+  const handlePathChange = (value: string) => {
+    setPath(value);
+    setIsDirty(true);
+  };
+
+  const handleSave = () => {
+    saveMutation.mutate();
+  };
+
+  if (isLoading) {
+    return (
+      <div className="flex flex-col items-center justify-center h-full p-8">
+        <Loading01
+          size={32}
+          className="animate-spin text-muted-foreground mb-4"
+        />
+        <p className="text-sm text-muted-foreground">Loading page...</p>
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className="flex flex-col items-center justify-center h-full p-8">
+        <AlertCircle size={48} className="text-destructive mb-4" />
+        <h3 className="text-lg font-medium mb-2">Error loading page</h3>
+        <p className="text-muted-foreground text-center">
+          {error instanceof Error ? error.message : "Unknown error"}
+        </p>
+      </div>
+    );
+  }
+
+  if (!page) {
+    return (
+      <div className="flex flex-col items-center justify-center h-full p-8">
+        <AlertCircle size={48} className="text-muted-foreground mb-4" />
+        <h3 className="text-lg font-medium mb-2">Page not found</h3>
+        <p className="text-muted-foreground text-center mb-4">
+          The page "{pageId}" could not be found.
+        </p>
+        <Button variant="outline" onClick={() => navigate({ to: "/" })}>
+          <ArrowLeft size={14} className="mr-1" />
+          Back to Pages
+        </Button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="flex flex-col h-full">
+      {/* Header with breadcrumb */}
+      <div className="flex items-center justify-between px-4 py-3 border-b border-border bg-background">
+        <div className="flex items-center gap-2 text-sm">
+          <button
+            type="button"
+            onClick={() => navigate({ to: "/" })}
+            className="text-muted-foreground hover:text-foreground transition-colors"
+          >
+            Pages
+          </button>
+          <span className="text-muted-foreground">/</span>
+          <span className="font-medium">{page.title}</span>
+        </div>
+        <Button
+          size="sm"
+          onClick={handleSave}
+          disabled={!isDirty || saveMutation.isPending}
+        >
+          {saveMutation.isPending ? (
+            <Loading01 size={14} className="mr-1 animate-spin" />
+          ) : (
+            <Save01 size={14} className="mr-1" />
+          )}
+          Save
+        </Button>
+      </div>
+
+      {/* Form content */}
+      <div className="flex-1 overflow-y-auto p-6">
+        <div className="max-w-2xl space-y-6">
+          {/* Title field */}
+          <div className="grid gap-2">
+            <Label htmlFor="edit-title">Title</Label>
+            <Input
+              id="edit-title"
+              value={title}
+              onChange={(e) => handleTitleChange(e.target.value)}
+              onKeyDown={(e) => {
+                if (e.key === "Enter" && isDirty) handleSave();
+              }}
+            />
+          </div>
+
+          {/* Path field */}
+          <div className="grid gap-2">
+            <Label htmlFor="edit-path">Path</Label>
+            <Input
+              id="edit-path"
+              value={path}
+              onChange={(e) => handlePathChange(e.target.value)}
+              onKeyDown={(e) => {
+                if (e.key === "Enter" && isDirty) handleSave();
+              }}
+            />
+          </div>
+
+          {/* Metadata (read-only) */}
+          <div className="border border-border rounded-lg p-4 space-y-3">
+            <h3 className="text-sm font-medium text-muted-foreground">
+              Metadata
+            </h3>
+            <div className="grid grid-cols-2 gap-3 text-sm">
+              <div>
+                <span className="text-muted-foreground">ID</span>
+                <p className="font-mono text-xs mt-0.5">{page.id}</p>
+              </div>
+              <div>
+                <span className="text-muted-foreground">Blocks</span>
+                <p className="mt-0.5">{page.blocks.length} blocks</p>
+              </div>
+              <div>
+                <span className="text-muted-foreground">Created</span>
+                <p className="mt-0.5">
+                  {formatTimestamp(page.metadata.createdAt)}
+                </p>
+              </div>
+              <div>
+                <span className="text-muted-foreground">Last Updated</span>
+                <p className="mt-0.5">
+                  {formatTimestamp(page.metadata.updatedAt)}
+                </p>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/packages/mesh-plugin-site-editor/client/components/pages-list.tsx b/packages/mesh-plugin-site-editor/client/components/pages-list.tsx
index 4af5583e87..03bbe1d684 100644
--- a/packages/mesh-plugin-site-editor/client/components/pages-list.tsx
+++ b/packages/mesh-plugin-site-editor/client/components/pages-list.tsx
@@ -1,17 +1,268 @@
 /**
  * Pages List Component
  *
- * Displays the list of pages managed by the site editor.
- * Full implementation will be added in plan 01-02.
+ * Displays all CMS pages with create and delete actions.
+ * Navigates to page editor on row click.
+ * Uses SITE_BINDING tools (READ_FILE, PUT_FILE, LIST_FILES) via page-api helpers.
  */
 
+import { useState } from "react";
+import { SITE_BINDING } from "@decocms/bindings/site";
+import { usePluginContext } from "@decocms/mesh-sdk/plugins";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { Button } from "@deco/ui/components/button.tsx";
+import { Input } from "@deco/ui/components/input.tsx";
+import { Label } from "@deco/ui/components/label.tsx";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from "@deco/ui/components/dialog.tsx";
+import {
+  File06,
+  Plus,
+  Trash01,
+  Loading01,
+  AlertCircle,
+} from "@untitledui/icons";
+import { toast } from "sonner";
+import { queryKeys } from "../lib/query-keys";
+import { siteEditorRouter } from "../lib/router";
+import { listPages, createPage, deletePage } from "../lib/page-api";
+
+function formatDate(dateStr: string): string {
+  if (!dateStr) return "-";
+  try {
+    return new Date(dateStr).toLocaleDateString(undefined, {
+      year: "numeric",
+      month: "short",
+      day: "numeric",
+      hour: "2-digit",
+      minute: "2-digit",
+    });
+  } catch {
+    return dateStr;
+  }
+}
+
 export default function PagesList() {
+  const { toolCaller, connectionId } = usePluginContext<typeof SITE_BINDING>();
+  const queryClient = useQueryClient();
+  const navigate = siteEditorRouter.useNavigate();
+
+  const [dialogOpen, setDialogOpen] = useState(false);
+  const [newTitle, setNewTitle] = useState("");
+  const [newPath, setNewPath] = useState("/");
+
+  // Fetch pages list
+  const {
+    data: pages = [],
+    isLoading,
+    error,
+  } = useQuery({
+    queryKey: queryKeys.pages.all(connectionId),
+    queryFn: () => listPages(toolCaller),
+  });
+
+  // Create page mutation
+  const createMutation = useMutation({
+    mutationFn: (input: { title: string; path: string }) =>
+      createPage(toolCaller, input),
+    onSuccess: (page) => {
+      toast.success(`Created page "${page.title}"`);
+      queryClient.invalidateQueries({
+        queryKey: queryKeys.pages.all(connectionId),
+      });
+      setDialogOpen(false);
+      setNewTitle("");
+      setNewPath("/");
+      navigate({
+        to: "/pages/$pageId",
+        params: { pageId: page.id },
+      });
+    },
+    onError: (err) => {
+      toast.error(
+        `Failed to create page: ${err instanceof Error ? err.message : "Unknown error"}`,
+      );
+    },
+  });
+
+  // Delete page mutation
+  const deleteMutation = useMutation({
+    mutationFn: (pageId: string) => deletePage(toolCaller, pageId),
+    onSuccess: () => {
+      toast.success("Page deleted");
+      queryClient.invalidateQueries({
+        queryKey: queryKeys.pages.all(connectionId),
+      });
+    },
+    onError: (err) => {
+      toast.error(
+        `Failed to delete page: ${err instanceof Error ? err.message : "Unknown error"}`,
+      );
+    },
+  });
+
+  const handleCreate = () => {
+    if (!newTitle.trim()) return;
+    createMutation.mutate({ title: newTitle.trim(), path: newPath.trim() });
+  };
+
+  const handleDelete = (e: React.MouseEvent, pageId: string) => {
+    e.stopPropagation();
+    if (confirm("Are you sure you want to delete this page?")) {
+      deleteMutation.mutate(pageId);
+    }
+  };
+
+  if (error) {
+    return (
+      <div className="flex flex-col items-center justify-center h-full p-8">
+        <AlertCircle size={48} className="text-destructive mb-4" />
+        <h3 className="text-lg font-medium mb-2">Error loading pages</h3>
+        <p className="text-muted-foreground text-center">
+          {error instanceof Error ? error.message : "Unknown error"}
+        </p>
+      </div>
+    );
+  }
+
   return (
-    <div className="flex flex-col items-center justify-center h-full p-8">
-      <h3 className="text-lg font-medium mb-2">Pages</h3>
-      <p className="text-muted-foreground text-center max-w-md">
-        Pages will appear here once file listing is implemented.
-      </p>
+    <div className="flex flex-col h-full">
+      {/* Header */}
+      <div className="flex items-center justify-between px-4 py-3 border-b border-border bg-background">
+        <h2 className="text-sm font-medium">Pages</h2>
+        <Dialog open={dialogOpen} onOpenChange={setDialogOpen}>
+          <DialogTrigger asChild>
+            <Button variant="outline" size="sm">
+              <Plus size={14} className="mr-1" />
+              New Page
+            </Button>
+          </DialogTrigger>
+          <DialogContent>
+            <DialogHeader>
+              <DialogTitle>Create New Page</DialogTitle>
+              <DialogDescription>
+                Add a new page to your site. You can edit its content after
+                creation.
+              </DialogDescription>
+            </DialogHeader>
+            <div className="grid gap-4 py-4">
+              <div className="grid gap-2">
+                <Label htmlFor="page-title">Title</Label>
+                <Input
+                  id="page-title"
+                  placeholder="Home"
+                  value={newTitle}
+                  onChange={(e) => setNewTitle(e.target.value)}
+                  onKeyDown={(e) => {
+                    if (e.key === "Enter") handleCreate();
+                  }}
+                />
+              </div>
+              <div className="grid gap-2">
+                <Label htmlFor="page-path">Path</Label>
+                <Input
+                  id="page-path"
+                  placeholder="/"
+                  value={newPath}
+                  onChange={(e) => setNewPath(e.target.value)}
+                  onKeyDown={(e) => {
+                    if (e.key === "Enter") handleCreate();
+                  }}
+                />
+              </div>
+            </div>
+            <DialogFooter>
+              <Button
+                onClick={handleCreate}
+                disabled={!newTitle.trim() || createMutation.isPending}
+              >
+                {createMutation.isPending && (
+                  <Loading01 size={14} className="mr-1 animate-spin" />
+                )}
+                Create Page
+              </Button>
+            </DialogFooter>
+          </DialogContent>
+        </Dialog>
+      </div>
+
+      {/* Table header */}
+      <div className="flex items-center gap-3 px-4 py-2 border-b border-border bg-muted/30 text-sm font-medium text-muted-foreground">
+        <span className="flex-1">Title</span>
+        <span className="w-32">Path</span>
+        <span className="w-40 text-right">Last Updated</span>
+        <span className="w-10" />
+      </div>
+
+      {/* Page list */}
+      <div className="flex-1 overflow-y-auto">
+        {isLoading ? (
+          <div className="flex flex-col items-center justify-center py-12">
+            <Loading01
+              size={32}
+              className="animate-spin text-muted-foreground mb-4"
+            />
+            <p className="text-sm text-muted-foreground">Loading pages...</p>
+          </div>
+        ) : pages.length === 0 ? (
+          <div className="flex flex-col items-center justify-center py-12 text-center">
+            <File06 size={48} className="text-muted-foreground mb-4" />
+            <h3 className="text-lg font-medium mb-2">No pages yet</h3>
+            <p className="text-muted-foreground mb-4">
+              Create your first page to get started.
+            </p>
+            <Button variant="outline" onClick={() => setDialogOpen(true)}>
+              <Plus size={14} className="mr-1" />
+              New Page
+            </Button>
+          </div>
+        ) : (
+          pages.map((page) => (
+            <button
+              key={page.id}
+              type="button"
+              onClick={() =>
+                navigate({
+                  to: "/pages/$pageId",
+                  params: { pageId: page.id },
+                })
+              }
+              className="group flex items-center gap-3 px-4 py-2.5 w-full text-left hover:bg-muted/50 border-b border-border last:border-b-0 transition-colors"
+            >
+              <div className="flex items-center gap-2 flex-1 min-w-0">
+                <File06 size={16} className="text-muted-foreground shrink-0" />
+                <span className="truncate font-medium text-sm">
+                  {page.title}
+                </span>
+              </div>
+              <span className="text-sm text-muted-foreground w-32 truncate">
+                {page.path}
+              </span>
+              <span className="text-sm text-muted-foreground w-40 text-right">
+                {formatDate(page.updatedAt)}
+              </span>
+              <div className="w-10 flex justify-end">
+                <Button
+                  variant="ghost"
+                  size="sm"
+                  className="size-7 p-0 opacity-0 group-hover:opacity-100 text-destructive hover:text-destructive"
+                  onClick={(e) => handleDelete(e, page.id)}
+                  disabled={deleteMutation.isPending}
+                >
+                  <Trash01 size={14} />
+                </Button>
+              </div>
+            </button>
+          ))
+        )}
+      </div>
     </div>
   );
 }
diff --git a/packages/mesh-plugin-site-editor/client/lib/page-api.ts b/packages/mesh-plugin-site-editor/client/lib/page-api.ts
new file mode 100644
index 0000000000..febb025885
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/lib/page-api.ts
@@ -0,0 +1,178 @@
+/**
+ * Page API helpers
+ *
+ * Client-side page CRUD using SITE_BINDING tools (READ_FILE, PUT_FILE, LIST_FILES).
+ * These mirror the server-side CMS_PAGE_* tools but call through the plugin's
+ * toolCaller which is connected to the site's MCP.
+ */
+
+import { nanoid } from "nanoid";
+import type { TypedToolCaller } from "@decocms/bindings";
+import type { SiteBinding } from "@decocms/bindings/site";
+
+type ToolCaller = TypedToolCaller<SiteBinding>;
+
+export interface PageSummary {
+  id: string;
+  path: string;
+  title: string;
+  updatedAt: string;
+}
+
+export interface Page {
+  id: string;
+  path: string;
+  title: string;
+  blocks: unknown[];
+  metadata: {
+    description: string;
+    createdAt: string;
+    updatedAt: string;
+  };
+}
+
+const PAGES_PREFIX = ".deco/pages/";
+
+/**
+ * List all pages from .deco/pages/
+ */
+export async function listPages(
+  toolCaller: ToolCaller,
+): Promise<PageSummary[]> {
+  const listResult = await toolCaller("LIST_FILES", {
+    prefix: PAGES_PREFIX,
+  });
+
+  if (!listResult.files || listResult.files.length === 0) {
+    return [];
+  }
+
+  const pages: PageSummary[] = [];
+
+  for (const file of listResult.files) {
+    if (!file.path.endsWith(".json")) continue;
+
+    try {
+      const readResult = await toolCaller("READ_FILE", { path: file.path });
+      const page = JSON.parse(readResult.content);
+
+      if (page.deleted) continue;
+
+      pages.push({
+        id: page.id,
+        path: page.path,
+        title: page.title,
+        updatedAt: page.metadata?.updatedAt ?? "",
+      });
+    } catch {
+      // Skip unreadable files
+      continue;
+    }
+  }
+
+  // Sort by updatedAt descending
+  pages.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+
+  return pages;
+}
+
+/**
+ * Get a single page by ID
+ */
+export async function getPage(
+  toolCaller: ToolCaller,
+  pageId: string,
+): Promise<Page | null> {
+  try {
+    const result = await toolCaller("READ_FILE", {
+      path: `${PAGES_PREFIX}${pageId}.json`,
+    });
+
+    const page = JSON.parse(result.content);
+    if (page.deleted) return null;
+    return page;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Create a new page
+ */
+export async function createPage(
+  toolCaller: ToolCaller,
+  input: { title: string; path: string },
+): Promise<Page> {
+  const id = `page_${nanoid(8)}`;
+  const now = new Date().toISOString();
+
+  const page: Page = {
+    id,
+    path: input.path,
+    title: input.title,
+    blocks: [],
+    metadata: {
+      description: "",
+      createdAt: now,
+      updatedAt: now,
+    },
+  };
+
+  await toolCaller("PUT_FILE", {
+    path: `${PAGES_PREFIX}${id}.json`,
+    content: JSON.stringify(page, null, 2),
+  });
+
+  return page;
+}
+
+/**
+ * Update an existing page (partial update)
+ */
+export async function updatePage(
+  toolCaller: ToolCaller,
+  pageId: string,
+  updates: { title?: string; path?: string; blocks?: unknown[] },
+): Promise<Page> {
+  const result = await toolCaller("READ_FILE", {
+    path: `${PAGES_PREFIX}${pageId}.json`,
+  });
+
+  const page = JSON.parse(result.content) as Page;
+
+  if (updates.title !== undefined) page.title = updates.title;
+  if (updates.path !== undefined) page.path = updates.path;
+  if (updates.blocks !== undefined) page.blocks = updates.blocks;
+
+  page.metadata = {
+    ...page.metadata,
+    updatedAt: new Date().toISOString(),
+  };
+
+  await toolCaller("PUT_FILE", {
+    path: `${PAGES_PREFIX}${pageId}.json`,
+    content: JSON.stringify(page, null, 2),
+  });
+
+  return page;
+}
+
+/**
+ * Delete a page by writing a tombstone
+ *
+ * Phase 1 limitation: SITE_BINDING doesn't include DELETE_FILE.
+ * We write a tombstone JSON that list/get operations skip.
+ */
+export async function deletePage(
+  toolCaller: ToolCaller,
+  pageId: string,
+): Promise<void> {
+  await toolCaller("PUT_FILE", {
+    path: `${PAGES_PREFIX}${pageId}.json`,
+    content: JSON.stringify(
+      { deleted: true, deletedAt: new Date().toISOString() },
+      null,
+      2,
+    ),
+  });
+}
diff --git a/packages/mesh-plugin-site-editor/client/lib/query-keys.ts b/packages/mesh-plugin-site-editor/client/lib/query-keys.ts
new file mode 100644
index 0000000000..d9b7da63ea
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/lib/query-keys.ts
@@ -0,0 +1,12 @@
+/**
+ * React Query keys for Site Editor plugin
+ */
+
+export const queryKeys = {
+  pages: {
+    all: (connectionId: string) =>
+      ["site-editor", "pages", connectionId] as const,
+    detail: (connectionId: string, pageId: string) =>
+      ["site-editor", "pages", connectionId, pageId] as const,
+  },
+} as const;
diff --git a/packages/mesh-plugin-site-editor/client/lib/router.ts b/packages/mesh-plugin-site-editor/client/lib/router.ts
index 4b1c17e111..100cdff02a 100644
--- a/packages/mesh-plugin-site-editor/client/lib/router.ts
+++ b/packages/mesh-plugin-site-editor/client/lib/router.ts
@@ -22,7 +22,7 @@ export const siteEditorRouter = createPluginRouter((ctx) => {
   const pageEditorRoute = createRoute({
     getParentRoute: () => ctx.parentRoute,
     path: "/pages/$pageId",
-    component: lazyRouteComponent(() => import("../components/pages-list")),
+    component: lazyRouteComponent(() => import("../components/page-editor")),
   });
 
   const sectionsRoute = createRoute({

From dec863983f5f999458090f7e7ffd34c92b792643 Mon Sep 17 00:00:00 2001
From: Guilherme Rodrigues <gui@deco.cx>
Date: Sat, 14 Feb 2026 10:00:50 -0300
Subject: [PATCH 06/26] feat(02-01): scanner pipeline -- types, extract,
 discover, schema

- Add ts-morph and ts-json-schema-generator dependencies
- Create BlockDefinition, ComponentInfo, ScanResult types in types.ts
- Implement createProjectFromMCP in extract.ts (in-memory ts-morph from MCP files)
- Implement discoverComponents in discover.ts (default + named export detection)
- Implement generateSchema in schema.ts (JSON Schema generation with $ref inlining)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/mesh-plugin-site-editor/package.json |   2 +
 .../server/scanner/discover.ts                | 305 ++++++++++++++++++
 .../server/scanner/extract.ts                 | 108 +++++++
 .../server/scanner/schema.ts                  | 142 ++++++++
 .../server/scanner/types.ts                   | 118 +++++++
 5 files changed, 675 insertions(+)
 create mode 100644 packages/mesh-plugin-site-editor/server/scanner/discover.ts
 create mode 100644 packages/mesh-plugin-site-editor/server/scanner/extract.ts
 create mode 100644 packages/mesh-plugin-site-editor/server/scanner/schema.ts
 create mode 100644 packages/mesh-plugin-site-editor/server/scanner/types.ts

diff --git a/packages/mesh-plugin-site-editor/package.json b/packages/mesh-plugin-site-editor/package.json
index 1ca5216186..2a127d9e5f 100644
--- a/packages/mesh-plugin-site-editor/package.json
+++ b/packages/mesh-plugin-site-editor/package.json
@@ -16,6 +16,8 @@
     "@decocms/mesh-sdk": "workspace:*",
     "@deco/ui": "workspace:*",
     "@untitledui/icons": "^0.0.19",
+    "ts-morph": "^27.0.2",
+    "ts-json-schema-generator": "^2.4.0",
     "zod": "^4.0.0"
   },
   "devDependencies": {
diff --git a/packages/mesh-plugin-site-editor/server/scanner/discover.ts b/packages/mesh-plugin-site-editor/server/scanner/discover.ts
new file mode 100644
index 0000000000..dfc7a8d213
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/server/scanner/discover.ts
@@ -0,0 +1,305 @@
+/**
+ * Discover - Component Discovery from ts-morph Project
+ *
+ * Finds exported React components in a ts-morph Project by checking for:
+ * - Default exports that are functions with a typed props parameter
+ * - Named exports whose return type suggests JSX output
+ *
+ * Only .tsx files are inspected since components must return JSX.
+ */
+
+import {
+  type Project,
+  type SourceFile,
+  SyntaxKind,
+  type FunctionDeclaration,
+  type VariableDeclaration,
+  type ArrowFunction,
+  type FunctionExpression,
+} from "ts-morph";
+import type { ComponentInfo } from "./types.js";
+
+/**
+ * JSX return type indicators. If a function's return type text contains any of
+ * these, it's likely a React component.
+ */
+const JSX_RETURN_PATTERNS = [
+  "JSX.Element",
+  "ReactNode",
+  "ReactElement",
+  "React.FC",
+  "React.FunctionComponent",
+  "Element",
+];
+
+/**
+ * Discover exported React components in the project's .tsx source files.
+ *
+ * @param project - ts-morph Project populated with source files
+ * @returns Array of discovered components with their metadata
+ */
+export function discoverComponents(project: Project): ComponentInfo[] {
+  const components: ComponentInfo[] = [];
+
+  for (const sourceFile of project.getSourceFiles()) {
+    const filePath = sourceFile.getFilePath();
+    if (!filePath.endsWith(".tsx")) continue;
+
+    // Try default export first (most common pattern for React components)
+    const defaultComponent = extractDefaultExport(sourceFile, filePath);
+    if (defaultComponent) {
+      components.push(defaultComponent);
+      continue; // One component per file for default exports
+    }
+
+    // Check named exports for component-like functions
+    const namedComponents = extractNamedExports(sourceFile, filePath);
+    components.push(...namedComponents);
+  }
+
+  return components;
+}
+
+/**
+ * Extract component info from a file's default export.
+ */
+function extractDefaultExport(
+  sourceFile: SourceFile,
+  filePath: string,
+): ComponentInfo | null {
+  const defaultExportSymbol = sourceFile.getDefaultExportSymbol();
+  if (!defaultExportSymbol) return null;
+
+  const declarations = defaultExportSymbol.getDeclarations();
+
+  for (const decl of declarations) {
+    // Pattern: export default function Hero(props: HeroProps) { ... }
+    if (decl.isKind(SyntaxKind.FunctionDeclaration)) {
+      return extractFromFunction(
+        decl as FunctionDeclaration,
+        sourceFile,
+        filePath,
+      );
+    }
+
+    // Pattern: export default (props: HeroProps) => { ... }
+    // or: const Hero = (props: HeroProps) => { ... }; export default Hero;
+    if (decl.isKind(SyntaxKind.VariableDeclaration)) {
+      const varDecl = decl as VariableDeclaration;
+      const initializer = varDecl.getInitializer();
+
+      if (
+        initializer?.isKind(SyntaxKind.ArrowFunction) ||
+        initializer?.isKind(SyntaxKind.FunctionExpression)
+      ) {
+        const fn = initializer as ArrowFunction | FunctionExpression;
+        return extractFromCallable(fn, varDecl.getName(), sourceFile, filePath);
+      }
+    }
+
+    // Pattern: export default expression (may resolve to a function)
+    if (decl.isKind(SyntaxKind.ExportAssignment)) {
+      // Try to resolve the expression
+      const expr = decl.getExpression();
+      if (!expr) continue;
+
+      // If it's an identifier referencing a variable/function
+      const symbol = expr.getSymbol();
+      if (!symbol) continue;
+
+      for (const symDecl of symbol.getDeclarations()) {
+        if (symDecl.isKind(SyntaxKind.FunctionDeclaration)) {
+          return extractFromFunction(
+            symDecl as FunctionDeclaration,
+            sourceFile,
+            filePath,
+          );
+        }
+        if (symDecl.isKind(SyntaxKind.VariableDeclaration)) {
+          const init = (symDecl as VariableDeclaration).getInitializer();
+          if (
+            init?.isKind(SyntaxKind.ArrowFunction) ||
+            init?.isKind(SyntaxKind.FunctionExpression)
+          ) {
+            return extractFromCallable(
+              init as ArrowFunction | FunctionExpression,
+              (symDecl as VariableDeclaration).getName(),
+              sourceFile,
+              filePath,
+            );
+          }
+        }
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Extract component info from a function declaration.
+ */
+function extractFromFunction(
+  fn: FunctionDeclaration,
+  sourceFile: SourceFile,
+  filePath: string,
+): ComponentInfo | null {
+  const params = fn.getParameters();
+  if (params.length === 0) return null; // No props = no editable props
+
+  const propsParam = params[0];
+  const propsType = propsParam.getType();
+  const propsTypeName =
+    propsType.getAliasSymbol()?.getName() ??
+    propsType.getSymbol()?.getName() ??
+    null;
+
+  // Skip if the type resolved to an anonymous/literal type with no properties
+  if (!propsTypeName && propsType.getProperties().length === 0) return null;
+
+  return {
+    name: fn.getName() ?? sourceFile.getBaseNameWithoutExtension(),
+    filePath,
+    propsTypeName,
+    jsDocDescription: extractJsDoc(fn),
+  };
+}
+
+/**
+ * Extract component info from an arrow function or function expression.
+ */
+function extractFromCallable(
+  fn: ArrowFunction | FunctionExpression,
+  name: string,
+  sourceFile: SourceFile,
+  filePath: string,
+): ComponentInfo | null {
+  const params = fn.getParameters();
+  if (params.length === 0) return null;
+
+  const propsParam = params[0];
+  const propsType = propsParam.getType();
+  const propsTypeName =
+    propsType.getAliasSymbol()?.getName() ??
+    propsType.getSymbol()?.getName() ??
+    null;
+
+  if (!propsTypeName && propsType.getProperties().length === 0) return null;
+
+  return {
+    name: name || sourceFile.getBaseNameWithoutExtension(),
+    filePath,
+    propsTypeName,
+    jsDocDescription: extractJsDocFromParent(fn),
+  };
+}
+
+/**
+ * Extract named component exports (functions returning JSX types).
+ */
+function extractNamedExports(
+  sourceFile: SourceFile,
+  filePath: string,
+): ComponentInfo[] {
+  const components: ComponentInfo[] = [];
+
+  const exportedDeclarations = sourceFile.getExportedDeclarations();
+
+  for (const [name, declarations] of exportedDeclarations) {
+    if (name === "default") continue; // Already handled
+
+    for (const decl of declarations) {
+      if (decl.isKind(SyntaxKind.FunctionDeclaration)) {
+        const fn = decl as FunctionDeclaration;
+        const returnTypeText = fn.getReturnType().getText();
+
+        if (looksLikeJSX(returnTypeText)) {
+          const info = extractFromFunction(fn, sourceFile, filePath);
+          if (info) {
+            info.name = name; // Use the export name
+            components.push(info);
+          }
+        }
+      }
+
+      if (decl.isKind(SyntaxKind.VariableDeclaration)) {
+        const varDecl = decl as VariableDeclaration;
+        const init = varDecl.getInitializer();
+        if (
+          init?.isKind(SyntaxKind.ArrowFunction) ||
+          init?.isKind(SyntaxKind.FunctionExpression)
+        ) {
+          const fn = init as ArrowFunction | FunctionExpression;
+          const returnTypeText = fn.getReturnType().getText();
+
+          if (looksLikeJSX(returnTypeText)) {
+            const info = extractFromCallable(fn, name, sourceFile, filePath);
+            if (info) {
+              components.push(info);
+            }
+          }
+        }
+      }
+    }
+  }
+
+  return components;
+}
+
+/**
+ * Check if a return type text indicates JSX output.
+ */
+function looksLikeJSX(returnTypeText: string): boolean {
+  return JSX_RETURN_PATTERNS.some((pattern) =>
+    returnTypeText.includes(pattern),
+  );
+}
+
+/**
+ * Extract JSDoc description from a function declaration.
+ */
+function extractJsDoc(fn: FunctionDeclaration): string {
+  const jsDocs = fn.getJsDocs();
+  if (jsDocs.length === 0) return "";
+
+  const lastDoc = jsDocs[jsDocs.length - 1];
+
+  // Try @description tag first
+  const descTag = lastDoc
+    .getTags()
+    .find((t) => t.getTagName() === "description");
+  if (descTag) {
+    return descTag.getCommentText()?.trim() ?? "";
+  }
+
+  // Fall back to the main comment body
+  return lastDoc.getDescription()?.trim() ?? "";
+}
+
+/**
+ * Extract JSDoc from parent node (for arrow functions in variable declarations).
+ */
+function extractJsDocFromParent(
+  fn: ArrowFunction | FunctionExpression,
+): string {
+  const parent = fn.getParent();
+  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();
+    if (jsDocs.length > 0) {
+      const lastDoc = jsDocs[jsDocs.length - 1];
+      const descTag = lastDoc
+        .getTags()
+        .find((t) => t.getTagName() === "description");
+      if (descTag) {
+        return descTag.getCommentText()?.trim() ?? "";
+      }
+      return lastDoc.getDescription()?.trim() ?? "";
+    }
+  }
+
+  return "";
+}
diff --git a/packages/mesh-plugin-site-editor/server/scanner/extract.ts b/packages/mesh-plugin-site-editor/server/scanner/extract.ts
new file mode 100644
index 0000000000..29b059d86f
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/server/scanner/extract.ts
@@ -0,0 +1,108 @@
+/**
+ * Extract - In-Memory ts-morph Project from MCP Files
+ *
+ * Reads source files through an MCP proxy (LIST_FILES, READ_FILE) and creates
+ * an in-memory ts-morph Project for analysis. No direct filesystem access needed.
+ */
+
+import {
+  type CompilerOptions,
+  ModuleKind,
+  ModuleResolutionKind,
+  Project,
+  ScriptTarget,
+  ts,
+} from "ts-morph";
+
+/**
+ * MCP proxy interface matching the pattern used by server tools.
+ * The proxy is obtained via `ctx.createMCPProxy(connectionId)`.
+ */
+export interface MCPProxy {
+  callTool(args: {
+    name: string;
+    arguments: Record<string, unknown>;
+  }): Promise<{
+    content?: Array<{ text?: string }>;
+    isError?: boolean;
+  }>;
+  close?(): Promise<void>;
+}
+
+const COMPILER_OPTIONS: CompilerOptions = {
+  target: ScriptTarget.ES2020,
+  jsx: ts.JsxEmit.ReactJSX,
+  module: ModuleKind.ESNext,
+  moduleResolution: ModuleResolutionKind.Bundler,
+  strict: true,
+  skipLibCheck: true,
+  skipDefaultLibCheck: true,
+};
+
+/**
+ * Create an in-memory ts-morph Project populated with source files read through MCP.
+ *
+ * @param proxy - MCP proxy for calling LIST_FILES and READ_FILE
+ * @param patterns - Directory prefixes to scan (e.g., ["sections/", "components/"])
+ * @returns Populated ts-morph Project
+ */
+export async function createProjectFromMCP(
+  proxy: MCPProxy,
+  patterns: string[],
+): Promise<Project> {
+  const project = new Project({
+    useInMemoryFileSystem: true,
+    compilerOptions: COMPILER_OPTIONS,
+  });
+
+  for (const pattern of patterns) {
+    try {
+      const listResult = await proxy.callTool({
+        name: "LIST_FILES",
+        arguments: { prefix: pattern },
+      });
+
+      const listContent = listResult.content?.[0]?.text;
+      if (!listContent) continue;
+
+      let fileList: { files?: Array<{ path: string }>; count?: number };
+      try {
+        fileList = JSON.parse(listContent);
+      } catch {
+        continue;
+      }
+
+      if (!fileList.files || fileList.files.length === 0) continue;
+
+      for (const file of fileList.files) {
+        if (!file.path.endsWith(".ts") && !file.path.endsWith(".tsx")) {
+          continue;
+        }
+
+        try {
+          const readResult = await proxy.callTool({
+            name: "READ_FILE",
+            arguments: { path: file.path },
+          });
+
+          const content = readResult.content?.[0]?.text;
+          if (!content) continue;
+
+          // Normalize path to start with / for ts-morph in-memory FS
+          const normalizedPath = file.path.startsWith("/")
+            ? file.path
+            : `/${file.path}`;
+          project.createSourceFile(normalizedPath, content);
+        } catch {
+          // Skip unreadable files -- log would go here in production
+          continue;
+        }
+      }
+    } catch {
+      // Skip patterns that fail to list -- non-fatal
+      continue;
+    }
+  }
+
+  return project;
+}
diff --git a/packages/mesh-plugin-site-editor/server/scanner/schema.ts b/packages/mesh-plugin-site-editor/server/scanner/schema.ts
new file mode 100644
index 0000000000..8af468155f
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/server/scanner/schema.ts
@@ -0,0 +1,142 @@
+/**
+ * Schema - JSON Schema Generation from ts-morph Types
+ *
+ * Uses ts-json-schema-generator to convert TypeScript prop types into
+ * JSON Schema 7. Feeds the ts-morph in-memory program to the generator
+ * for seamless integration without filesystem access.
+ *
+ * Falls back to a permissive schema on failure -- complex types (conditional types,
+ * template literals, deep utility types) may not be representable in JSON Schema.
+ */
+
+import type { Project } from "ts-morph";
+import {
+  SchemaGenerator,
+  createParser,
+  createFormatter,
+  DEFAULT_CONFIG,
+  type CompletedConfig,
+} from "ts-json-schema-generator";
+import type ts from "typescript";
+import type { JSONSchema7 } from "./types.js";
+
+/**
+ * Permissive fallback schema used when generation fails.
+ */
+const FALLBACK_SCHEMA: JSONSchema7 = {
+  type: "object",
+  additionalProperties: true,
+  description: "Schema could not be auto-generated. Edit manually or re-scan.",
+};
+
+/**
+ * Generate a JSON Schema from a TypeScript type using ts-json-schema-generator.
+ *
+ * @param project - ts-morph Project with in-memory source files
+ * @param typeName - The TypeScript type name (e.g., "HeroProps")
+ * @param filePath - Source file path containing the type
+ * @returns JSON Schema 7 for the type, or a permissive fallback on failure
+ */
+export function generateSchema(
+  project: Project,
+  typeName: string,
+  filePath: string,
+): JSONSchema7 {
+  try {
+    // Cast through unknown to bridge the TypeScript version mismatch between
+    // ts-morph's bundled TS and ts-json-schema-generator's TS.
+    // Both expose the same ts.Program interface but from different TS installations.
+    const program = project.getProgram()
+      .compilerObject as unknown as ts.Program;
+
+    const config: CompletedConfig = {
+      ...DEFAULT_CONFIG,
+      path: filePath,
+      type: typeName,
+      expose: "none",
+      jsDoc: "extended",
+      skipTypeCheck: true,
+      topRef: false,
+      additionalProperties: false,
+    };
+
+    const parser = createParser(program, config);
+    const formatter = createFormatter(config);
+    const generator = new SchemaGenerator(program, parser, formatter, config);
+
+    const schema = generator.createSchema(typeName) as JSONSchema7;
+
+    // Post-process: inline $ref definitions so @rjsf can render without issues
+    return inlineRefs(schema);
+  } catch {
+    // Schema generation failed -- return permissive fallback
+    // Common causes: conditional types, complex mapped types, missing imports
+    return { ...FALLBACK_SCHEMA };
+  }
+}
+
+/**
+ * Inline $ref pointers by resolving them from $defs/definitions.
+ * This flattens the schema so @rjsf doesn't need to handle $ref resolution.
+ */
+function inlineRefs(schema: JSONSchema7): JSONSchema7 {
+  const defs = schema.$defs ?? schema.definitions ?? {};
+  if (Object.keys(defs).length === 0) {
+    return schema;
+  }
+
+  const resolved = resolveRefs(schema, defs);
+
+  // Remove definition containers from the output
+  delete resolved.$defs;
+  delete resolved.definitions;
+
+  return resolved;
+}
+
+/**
+ * Recursively resolve $ref pointers in a schema object.
+ * Uses a depth limit to avoid infinite recursion on circular refs.
+ */
+function resolveRefs(
+  node: JSONSchema7,
+  defs: Record<string, JSONSchema7>,
+  depth = 0,
+): JSONSchema7 {
+  if (depth > 10) return node; // Bail on deep/circular refs
+
+  // If this node is a $ref, resolve it
+  if (node.$ref) {
+    const refPath = node.$ref;
+    // Handle #/$defs/TypeName or #/definitions/TypeName
+    const match = refPath.match(/^#\/(?:\$defs|definitions)\/(.+)$/);
+    if (match && defs[match[1]]) {
+      // Merge the resolved def (may itself contain $refs)
+      return resolveRefs({ ...defs[match[1]] }, defs, depth + 1);
+    }
+    return node;
+  }
+
+  // Recursively process all schema-valued properties
+  const result: JSONSchema7 = {};
+
+  for (const [key, value] of Object.entries(node)) {
+    if (key === "$defs" || key === "definitions") {
+      continue; // Skip definition containers
+    }
+
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      result[key] = resolveRefs(value as JSONSchema7, defs, depth + 1);
+    } else if (Array.isArray(value)) {
+      result[key] = value.map((item) =>
+        item && typeof item === "object"
+          ? resolveRefs(item as JSONSchema7, defs, depth + 1)
+          : item,
+      );
+    } else {
+      result[key] = value;
+    }
+  }
+
+  return result;
+}
diff --git a/packages/mesh-plugin-site-editor/server/scanner/types.ts b/packages/mesh-plugin-site-editor/server/scanner/types.ts
new file mode 100644
index 0000000000..195c691f60
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/server/scanner/types.ts
@@ -0,0 +1,118 @@
+/**
+ * Block Scanner Types
+ *
+ * Core type definitions used throughout the scanner pipeline:
+ * discover components -> extract props -> generate JSON Schema -> write block definitions.
+ */
+
+/**
+ * JSON Schema 7 type (simplified for block definitions).
+ * Using a local definition to avoid heavy external type dependencies.
+ */
+export interface JSONSchema7 {
+  $schema?: string;
+  $id?: string;
+  $ref?: string;
+  $defs?: Record<string, JSONSchema7>;
+  definitions?: Record<string, JSONSchema7>;
+  type?: string | string[];
+  title?: string;
+  description?: string;
+  default?: unknown;
+  examples?: unknown[];
+  enum?: unknown[];
+  const?: unknown;
+  properties?: Record<string, JSONSchema7>;
+  required?: string[];
+  additionalProperties?: boolean | JSONSchema7;
+  items?: JSONSchema7 | JSONSchema7[];
+  allOf?: JSONSchema7[];
+  anyOf?: JSONSchema7[];
+  oneOf?: JSONSchema7[];
+  not?: JSONSchema7;
+  if?: JSONSchema7;
+  then?: JSONSchema7;
+  else?: JSONSchema7;
+  format?: string;
+  minimum?: number;
+  maximum?: number;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  minItems?: number;
+  maxItems?: number;
+  uniqueItems?: boolean;
+  [key: string]: unknown;
+}
+
+/**
+ * Full block definition stored in .deco/blocks/{id}.json.
+ * This is the canonical format for all block data -- scanned, manual, or AI-generated.
+ */
+export interface BlockDefinition {
+  /** Unique ID derived from component path, e.g., "sections--Hero" */
+  id: string;
+  /** Source component path, e.g., "sections/Hero.tsx" */
+  component: string;
+  /** Human-readable label, e.g., "Hero Banner" */
+  label: string;
+  /** Category derived from directory, e.g., "Sections" */
+  category: string;
+  /** Description from JSDoc or manually provided */
+  description: string;
+  /** JSON Schema for the component's props */
+  schema: JSONSchema7;
+  /** Default prop values (empty initially) */
+  defaults: Record<string, unknown>;
+  /** Scan metadata */
+  metadata: {
+    /** ISO timestamp of last scan */
+    scannedAt: string;
+    /** How this block was discovered */
+    scanMethod: "ts-morph" | "manual" | "ai-agent";
+    /** Original TypeScript type name for the props */
+    propsTypeName: string | null;
+    /** Fields manually edited by user (preserved during re-scan) */
+    customized: string[];
+  };
+}
+
+/**
+ * Intermediate component info extracted during discovery phase.
+ */
+export interface ComponentInfo {
+  /** Component name (function name or file basename) */
+  name: string;
+  /** Source file path within the project */
+  filePath: string;
+  /** TypeScript type name for the props parameter, or null */
+  propsTypeName: string | null;
+  /** JSDoc description from the component */
+  jsDocDescription: string;
+}
+
+/**
+ * Result of a scan operation.
+ */
+export interface ScanResult {
+  /** Summary of all discovered blocks */
+  blocks: BlockSummary[];
+  /** Errors encountered during scanning (non-fatal) */
+  errors: string[];
+}
+
+/**
+ * Lightweight block summary for list operations.
+ */
+export interface BlockSummary {
+  /** Block ID, e.g., "sections--Hero" */
+  id: string;
+  /** Source component path */
+  component: string;
+  /** Human-readable label */
+  label: string;
+  /** Category name */
+  category: string;
+  /** Number of top-level props */
+  propsCount: number;
+}

From 1fe08263c20b833655f990b9daaa85d51a3679b0 Mon Sep 17 00:00:00 2001
From: Guilherme Rodrigues <gui@deco.cx>
Date: Sat, 14 Feb 2026 10:03:35 -0300
Subject: [PATCH 07/26] feat(02-01): block server tools and client API helpers

- Add CMS_BLOCK_SCAN tool (ts-morph pipeline: extract -> discover -> schema -> write)
- Add CMS_BLOCK_LIST tool (read .deco/blocks/ summaries)
- Add CMS_BLOCK_GET tool (full block definition with schema)
- Add CMS_BLOCK_REGISTER tool (manual block registration)
- Register all 4 block tools in server/tools/index.ts (now 9 total)
- Add client block-api with listBlocks and getBlock via SITE_BINDING
- Add block query keys to query-keys.ts

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../client/lib/block-api.ts                   | 110 +++++++++
 .../client/lib/query-keys.ts                  |   9 +
 .../server/tools/block-get.ts                 |  74 ++++++
 .../server/tools/block-list.ts                | 102 ++++++++
 .../server/tools/block-register.ts            | 117 ++++++++++
 .../server/tools/block-scan.ts                | 218 ++++++++++++++++++
 .../server/tools/index.ts                     |   9 +
 7 files changed, 639 insertions(+)
 create mode 100644 packages/mesh-plugin-site-editor/client/lib/block-api.ts
 create mode 100644 packages/mesh-plugin-site-editor/server/tools/block-get.ts
 create mode 100644 packages/mesh-plugin-site-editor/server/tools/block-list.ts
 create mode 100644 packages/mesh-plugin-site-editor/server/tools/block-register.ts
 create mode 100644 packages/mesh-plugin-site-editor/server/tools/block-scan.ts

diff --git a/packages/mesh-plugin-site-editor/client/lib/block-api.ts b/packages/mesh-plugin-site-editor/client/lib/block-api.ts
new file mode 100644
index 0000000000..e8f05a8347
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/lib/block-api.ts
@@ -0,0 +1,110 @@
+/**
+ * Block API helpers
+ *
+ * Client-side block listing and fetching using SITE_BINDING tools (LIST_FILES, READ_FILE).
+ * Follows the same pattern as page-api.ts -- calls through the plugin's toolCaller
+ * which is connected to the site's MCP.
+ */
+
+import type { TypedToolCaller } from "@decocms/bindings";
+import type { SiteBinding } from "@decocms/bindings/site";
+
+type ToolCaller = TypedToolCaller<SiteBinding>;
+
+/**
+ * Block summary returned by list operations.
+ */
+export interface BlockSummary {
+  id: string;
+  component: string;
+  label: string;
+  category: string;
+  propsCount: number;
+}
+
+/**
+ * Full block definition returned by get operations.
+ */
+export interface BlockDefinition {
+  id: string;
+  component: string;
+  label: string;
+  category: string;
+  description: string;
+  schema: Record<string, unknown>;
+  defaults: Record<string, unknown>;
+  metadata: {
+    scannedAt: string;
+    scanMethod: "ts-morph" | "manual" | "ai-agent";
+    propsTypeName: string | null;
+    customized: string[];
+  };
+}
+
+const BLOCKS_PREFIX = ".deco/blocks/";
+
+/**
+ * List all blocks from .deco/blocks/
+ */
+export async function listBlocks(
+  toolCaller: ToolCaller,
+): Promise<BlockSummary[]> {
+  const listResult = await toolCaller("LIST_FILES", {
+    prefix: BLOCKS_PREFIX,
+  });
+
+  if (!listResult.files || listResult.files.length === 0) {
+    return [];
+  }
+
+  const blocks: BlockSummary[] = [];
+
+  for (const file of listResult.files) {
+    if (!file.path.endsWith(".json")) continue;
+
+    try {
+      const readResult = await toolCaller("READ_FILE", { path: file.path });
+      const block = JSON.parse(readResult.content);
+
+      if (block.deleted) continue;
+
+      const propsCount = Object.keys(block.schema?.properties ?? {}).length;
+
+      blocks.push({
+        id: block.id,
+        component: block.component,
+        label: block.label,
+        category: block.category ?? "Other",
+        propsCount,
+      });
+    } catch {
+      // Skip unreadable files
+      continue;
+    }
+  }
+
+  // Sort by label alphabetically
+  blocks.sort((a, b) => a.label.localeCompare(b.label));
+
+  return blocks;
+}
+
+/**
+ * Get a single block definition by ID
+ */
+export async function getBlock(
+  toolCaller: ToolCaller,
+  blockId: string,
+): Promise<BlockDefinition | null> {
+  try {
+    const result = await toolCaller("READ_FILE", {
+      path: `${BLOCKS_PREFIX}${blockId}.json`,
+    });
+
+    const block = JSON.parse(result.content);
+    if (block.deleted) return null;
+    return block;
+  } catch {
+    return null;
+  }
+}
diff --git a/packages/mesh-plugin-site-editor/client/lib/query-keys.ts b/packages/mesh-plugin-site-editor/client/lib/query-keys.ts
index d9b7da63ea..c738531a9d 100644
--- a/packages/mesh-plugin-site-editor/client/lib/query-keys.ts
+++ b/packages/mesh-plugin-site-editor/client/lib/query-keys.ts
@@ -9,4 +9,13 @@ export const queryKeys = {
     detail: (connectionId: string, pageId: string) =>
       ["site-editor", "pages", connectionId, pageId] as const,
   },
+  blocks: {
+    all: (connectionId: string) =>
+      ["site-editor", "blocks", connectionId] as const,
+    detail: (connectionId: string, blockId: string) =>
+      ["site-editor", "blocks", connectionId, blockId] as const,
+  },
 } as const;
+
+/** Shorthand for block query keys */
+export const blockKeys = queryKeys.blocks;
diff --git a/packages/mesh-plugin-site-editor/server/tools/block-get.ts b/packages/mesh-plugin-site-editor/server/tools/block-get.ts
new file mode 100644
index 0000000000..f12a5a72c0
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/server/tools/block-get.ts
@@ -0,0 +1,74 @@
+/**
+ * CMS_BLOCK_GET Tool
+ *
+ * Reads a single block definition by ID from .deco/blocks/{blockId}.json via MCP.
+ * Returns the full BlockDefinition including JSON Schema.
+ */
+
+import { z } from "zod";
+import type { ServerPluginToolDefinition } from "@decocms/bindings/server-plugin";
+
+export const BLOCK_GET: ServerPluginToolDefinition = {
+  name: "CMS_BLOCK_GET",
+  description:
+    "Get a single CMS block definition by ID, including its full JSON Schema.",
+  inputSchema: z.object({
+    connectionId: z.string().describe("MCP connection ID for the site"),
+    blockId: z.string().describe('Block ID (e.g., "sections--Hero")'),
+  }),
+  outputSchema: z.object({
+    block: z
+      .object({
+        id: z.string(),
+        component: z.string(),
+        label: z.string(),
+        category: z.string(),
+        description: z.string(),
+        schema: z.record(z.string(), z.unknown()),
+        defaults: z.record(z.string(), z.unknown()),
+        metadata: z.object({
+          scannedAt: z.string(),
+          scanMethod: z.string(),
+          propsTypeName: z.string().nullable(),
+          customized: z.array(z.string()),
+        }),
+      })
+      .nullable(),
+  }),
+
+  handler: async (input, ctx) => {
+    const { connectionId, blockId } = input as {
+      connectionId: string;
+      blockId: string;
+    };
+    const proxy = await ctx.createMCPProxy(connectionId);
+
+    try {
+      const readResult = await proxy.callTool({
+        name: "READ_FILE",
+        arguments: { path: `.deco/blocks/${blockId}.json` },
+      });
+
+      if (readResult.isError) {
+        return { block: null };
+      }
+
+      const content = readResult.content?.[0]?.text;
+      if (!content) {
+        return { block: null };
+      }
+
+      try {
+        const block = JSON.parse(content);
+        if (block.deleted) {
+          return { block: null };
+        }
+        return { block };
+      } catch {
+        return { block: null };
+      }
+    } finally {
+      await proxy.close?.();
+    }
+  },
+};
diff --git a/packages/mesh-plugin-site-editor/server/tools/block-list.ts b/packages/mesh-plugin-site-editor/server/tools/block-list.ts
new file mode 100644
index 0000000000..ef52a8d59c
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/server/tools/block-list.ts
@@ -0,0 +1,102 @@
+/**
+ * CMS_BLOCK_LIST Tool
+ *
+ * Lists all block definitions from .deco/blocks/ via MCP file operations.
+ * Returns summaries with id, component, label, category, and prop count.
+ */
+
+import { z } from "zod";
+import type { ServerPluginToolDefinition } from "@decocms/bindings/server-plugin";
+
+export const BLOCK_LIST: ServerPluginToolDefinition = {
+  name: "CMS_BLOCK_LIST",
+  description:
+    "List all CMS block definitions with their metadata (id, component, label, category, propsCount).",
+  inputSchema: z.object({
+    connectionId: z.string().describe("MCP connection ID for the site"),
+  }),
+  outputSchema: z.object({
+    blocks: z.array(
+      z.object({
+        id: z.string(),
+        component: z.string(),
+        label: z.string(),
+        category: z.string(),
+        propsCount: z.number(),
+      }),
+    ),
+  }),
+
+  handler: async (input, ctx) => {
+    const { connectionId } = input as { connectionId: string };
+    const proxy = await ctx.createMCPProxy(connectionId);
+
+    try {
+      const listResult = await proxy.callTool({
+        name: "LIST_FILES",
+        arguments: { prefix: ".deco/blocks/" },
+      });
+
+      const listContent = listResult.content?.[0]?.text;
+      if (!listContent) {
+        return { blocks: [] };
+      }
+
+      let fileList: { files?: Array<{ path: string }>; count?: number };
+      try {
+        fileList = JSON.parse(listContent);
+      } catch {
+        return { blocks: [] };
+      }
+
+      if (!fileList.files || fileList.files.length === 0) {
+        return { blocks: [] };
+      }
+
+      const blocks: Array<{
+        id: string;
+        component: string;
+        label: string;
+        category: string;
+        propsCount: number;
+      }> = [];
+
+      for (const file of fileList.files) {
+        if (!file.path.endsWith(".json")) continue;
+
+        try {
+          const readResult = await proxy.callTool({
+            name: "READ_FILE",
+            arguments: { path: file.path },
+          });
+
+          const content = readResult.content?.[0]?.text;
+          if (!content) continue;
+
+          const block = JSON.parse(content);
+          if (block.deleted) continue; // Skip tombstoned blocks
+
+          const propsCount = Object.keys(block.schema?.properties ?? {}).length;
+
+          blocks.push({
+            id: block.id,
+            component: block.component,
+            label: block.label,
+            category: block.category ?? "Other",
+            propsCount,
+          });
+        } catch {
+          // Skip files that can't be read or parsed
+          continue;
+        }
+      }
+
+      // Sort by label alphabetically
+      blocks.sort((a, b) => a.label.localeCompare(b.label));
+
+      return { blocks };
+    } finally {
+      await proxy.close?.();
+    }
+  },
+};
diff --git a/packages/mesh-plugin-site-editor/server/tools/block-register.ts b/packages/mesh-plugin-site-editor/server/tools/block-register.ts
new file mode 100644
index 0000000000..50db2e1f5e
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/server/tools/block-register.ts
@@ -0,0 +1,117 @@
+/**
+ * CMS_BLOCK_REGISTER Tool
+ *
+ * Manually register a block definition without running the ts-morph scanner.
+ * Useful for components the scanner can't analyze, or for hand-crafted block definitions.
+ */
+
+import { z } from "zod";
+import type { ServerPluginToolDefinition } from "@decocms/bindings/server-plugin";
+
+/**
+ * Derive a block ID from a component path.
+ * e.g., "sections/Hero.tsx" -> "sections--Hero"
+ */
+function componentToId(component: string): string {
+  return component
+    .replace(/\.\w+$/, "") // strip extension
+    .replace(/\//g, "--"); // replace / with --
+}
+
+export const BLOCK_REGISTER: ServerPluginToolDefinition = {
+  name: "CMS_BLOCK_REGISTER",
+  description:
+    "Manually register a block definition without running the scanner.",
+  inputSchema: z.object({
+    connectionId: z.string().describe("MCP connection ID for the site"),
+    block: z.object({
+      component: z
+        .string()
+        .describe("Component file path (e.g., sections/Hero.tsx)"),
+      label: z.string().describe("Human-readable label"),
+      category: z.string().optional().describe("Block category"),
+      description: z.string().optional().describe("Block description"),
+      schema: z
+        .record(z.string(), z.unknown())
+        .describe("JSON Schema for the block props"),
+      defaults: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe("Default prop values"),
+    }),
+  }),
+  outputSchema: z.object({
+    block: z.object({
+      id: z.string(),
+      component: z.string(),
+      label: z.string(),
+      category: z.string(),
+      propsCount: z.number(),
+    }),
+  }),
+
+  handler: async (input, ctx) => {
+    const { connectionId, block: blockInput } = input as {
+      connectionId: string;
+      block: {
+        component: string;
+        label: string;
+        category?: string;
+        description?: string;
+        schema: Record<string, unknown>;
+        defaults?: Record<string, unknown>;
+      };
+    };
+    const proxy = await ctx.createMCPProxy(connectionId);
+
+    try {
+      const id = componentToId(blockInput.component);
+      const firstSegment = blockInput.component.split("/")[0] ?? "Other";
+      const category =
+        blockInput.category ??
+        firstSegment.charAt(0).toUpperCase() + firstSegment.slice(1);
+
+      const now = new Date().toISOString();
+
+      const blockDef = {
+        id,
+        component: blockInput.component,
+        label: blockInput.label,
+        category,
+        description: blockInput.description ?? "",
+        schema: blockInput.schema,
+        defaults: blockInput.defaults ?? {},
+        metadata: {
+          scannedAt: now,
+          scanMethod: "manual" as const,
+          propsTypeName: null,
+          customized: [] as string[],
+        },
+      };
+
+      await proxy.callTool({
+        name: "PUT_FILE",
+        arguments: {
+          path: `.deco/blocks/${id}.json`,
+          content: JSON.stringify(blockDef, null, 2),
+        },
+      });
+
+      const propsCount = Object.keys(
+        (blockInput.schema as Record<string, unknown>).properties ?? {},
+      ).length;
+
+      return {
+        block: {
+          id,
+          component: blockInput.component,
+          label: blockInput.label,
+          category,
+          propsCount,
+        },
+      };
+    } finally {
+      await proxy.close?.();
+    }
+  },
+};
diff --git a/packages/mesh-plugin-site-editor/server/tools/block-scan.ts b/packages/mesh-plugin-site-editor/server/tools/block-scan.ts
new file mode 100644
index 0000000000..e46b4e02f8
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/server/tools/block-scan.ts
@@ -0,0 +1,218 @@
+/**
+ * CMS_BLOCK_SCAN Tool
+ *
+ * Scans a site's TypeScript codebase via MCP to discover React components,
+ * generate JSON Schema for their props, and write block definitions to .deco/blocks/.
+ *
+ * Pipeline: createProjectFromMCP -> discoverComponents -> generateSchema -> write blocks
+ */
+
+import { z } from "zod";
+import type { ServerPluginToolDefinition } from "@decocms/bindings/server-plugin";
+import { createProjectFromMCP } from "../scanner/extract.js";
+import { discoverComponents } from "../scanner/discover.js";
+import { generateSchema } from "../scanner/schema.js";
+import type { BlockDefinition, BlockSummary } from "../scanner/types.js";
+
+const DEFAULT_PATTERNS = ["sections/", "components/"];
+
+/**
+ * Derive a block ID from a component path.
+ * e.g., "sections/Hero.tsx" -> "sections--Hero"
+ */
+function componentToId(component: string): string {
+  return component
+    .replace(/\.\w+$/, "") // strip extension
+    .replace(/\//g, "--"); // replace / with --
+}
+
+/**
+ * Convert a component name to a human-readable label.
+ * e.g., "HeroBanner" -> "Hero Banner"
+ */
+function nameToLabel(name: string): string {
+  return name.replace(/([a-z])([A-Z])/g, "$1 $2");
+}
+
+/**
+ * Derive category from the first directory segment.
+ * e.g., "sections/Hero.tsx" -> "Sections"
+ */
+function componentToCategory(component: string): string {
+  const firstSegment = component.split("/")[0] ?? "Other";
+  return firstSegment.charAt(0).toUpperCase() + firstSegment.slice(1);
+}
+
+export const BLOCK_SCAN: ServerPluginToolDefinition = {
+  name: "CMS_BLOCK_SCAN",
+  description:
+    "Scan a site's TypeScript codebase and generate block definitions in .deco/blocks/",
+  inputSchema: z.object({
+    connectionId: z.string().describe("MCP connection ID for the site"),
+    patterns: z
+      .array(z.string())
+      .optional()
+      .describe(
+        "File path prefixes to scan (default: ['sections/', 'components/'])",
+      ),
+  }),
+  outputSchema: z.object({
+    blocks: z.array(
+      z.object({
+        id: z.string(),
+        component: z.string(),
+        label: z.string(),
+        category: z.string(),
+        propsCount: z.number(),
+      }),
+    ),
+    errors: z.array(z.string()),
+  }),
+
+  handler: async (input, ctx) => {
+    const { connectionId, patterns = DEFAULT_PATTERNS } = input as {
+      connectionId: string;
+      patterns?: string[];
+    };
+    const proxy = await ctx.createMCPProxy(connectionId);
+
+    const blocks: BlockSummary[] = [];
+    const errors: string[] = [];
+
+    try {
+      // 1. Build in-memory ts-morph project from MCP files
+      const project = await createProjectFromMCP(proxy, patterns);
+
+      // 2. Discover components
+      const components = discoverComponents(project);
+
+      // 3. For each component, generate schema and write block definition
+      for (const comp of components) {
+        try {
+          // Normalize the component path (strip leading /)
+          const component = comp.filePath.startsWith("/")
+            ? comp.filePath.slice(1)
+            : comp.filePath;
+          const id = componentToId(component);
+          const label = nameToLabel(comp.name);
+          const category = componentToCategory(component);
+
+          // Generate JSON Schema for the props type
+          let schema = { type: "object" as const, additionalProperties: true };
+          if (comp.propsTypeName) {
+            schema = generateSchema(
+              project,
+              comp.propsTypeName,
+              comp.filePath,
+            ) as typeof schema;
+          }
+
+          const propsCount = Object.keys(
+            (schema as Record<string, unknown>).properties ?? {},
+          ).length;
+
+          // Check if an existing definition has customized fields to preserve
+          const blockDef = await buildBlockDefinition(
+            proxy,
+            id,
+            component,
+            label,
+            category,
+            comp.jsDocDescription,
+            schema,
+            comp.propsTypeName,
+          );
+
+          // Write block definition
+          await proxy.callTool({
+            name: "PUT_FILE",
+            arguments: {
+              path: `.deco/blocks/${id}.json`,
+              content: JSON.stringify(blockDef, null, 2),
+            },
+          });
+
+          blocks.push({ id, component, label, category, propsCount });
+        } catch (err) {
+          errors.push(
+            `Failed to process ${comp.name}: ${err instanceof Error ? err.message : String(err)}`,
+          );
+        }
+      }
+    } catch (err) {
+      errors.push(
+        `Scan failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    } finally {
+      await proxy.close?.();
+    }
+
+    return { blocks, errors };
+  },
+};
+
+/**
+ * Build a BlockDefinition, merging with existing data if user has customized fields.
+ */
+async function buildBlockDefinition(
+  // deno-lint-ignore no-explicit-any
+  proxy: any,
+  id: string,
+  component: string,
+  label: string,
+  category: string,
+  description: string,
+  schema: Record<string, unknown>,
+  propsTypeName: string | null,
+): Promise<BlockDefinition> {
+  const now = new Date().toISOString();
+
+  const newDef: BlockDefinition = {
+    id,
+    component,
+    label,
+    category,
+    description,
+    schema,
+    defaults: {},
+    metadata: {
+      scannedAt: now,
+      scanMethod: "ts-morph",
+      propsTypeName,
+      customized: [],
+    },
+  };
+
+  // Try to read existing block to preserve customized fields
+  try {
+    const readResult = await proxy.callTool({
+      name: "READ_FILE",
+      arguments: { path: `.deco/blocks/${id}.json` },
+    });
+
+    const content = readResult.content?.[0]?.text;
+    if (content) {
+      const existing = JSON.parse(content) as BlockDefinition;
+      const customized = existing.metadata?.customized ?? [];
+
+      if (customized.length > 0) {
+        // Preserve user-customized fields
+        if (customized.includes("label")) newDef.label = existing.label;
+        if (customized.includes("description")) {
+          newDef.description = existing.description;
+        }
+        if (customized.includes("category")) {
+          newDef.category = existing.category;
+        }
+        if (customized.includes("defaults")) {
+          newDef.defaults = existing.defaults;
+        }
+        newDef.metadata.customized = customized;
+      }
+    }
+  } catch {
+    // No existing block -- use new definition as-is
+  }
+
+  return newDef;
+}
diff --git a/packages/mesh-plugin-site-editor/server/tools/index.ts b/packages/mesh-plugin-site-editor/server/tools/index.ts
index 3a8f452cb6..8d4ec38d93 100644
--- a/packages/mesh-plugin-site-editor/server/tools/index.ts
+++ b/packages/mesh-plugin-site-editor/server/tools/index.ts
@@ -2,6 +2,7 @@
  * Site Editor Server Tools
  *
  * Page CRUD tools for managing CMS pages stored in .deco/pages/.
+ * Block scanner and management tools for .deco/blocks/.
  */
 
 import type { ServerPluginToolDefinition } from "@decocms/bindings/server-plugin";
@@ -10,6 +11,10 @@ import { PAGE_GET } from "./page-get";
 import { PAGE_CREATE } from "./page-create";
 import { PAGE_UPDATE } from "./page-update";
 import { PAGE_DELETE } from "./page-delete";
+import { BLOCK_SCAN } from "./block-scan";
+import { BLOCK_LIST } from "./block-list";
+import { BLOCK_GET } from "./block-get";
+import { BLOCK_REGISTER } from "./block-register";
 
 export const tools: ServerPluginToolDefinition[] = [
   PAGE_LIST,
@@ -17,4 +22,8 @@ export const tools: ServerPluginToolDefinition[] = [
   PAGE_CREATE,
   PAGE_UPDATE,
   PAGE_DELETE,
+  BLOCK_SCAN,
+  BLOCK_LIST,
+  BLOCK_GET,
+  BLOCK_REGISTER,
 ];

From b0ea78dd6c341889add7e394bd5e5ce11fd37620 Mon Sep 17 00:00:00 2001
From: Guilherme Rodrigues <gui@deco.cx>
Date: Sat, 14 Feb 2026 10:08:55 -0300
Subject: [PATCH 08/26] feat(02-02): add RJSF templates, widgets, and
 PropEditor component

- Custom FieldTemplate with type icons, labels, required indicators
- Custom ObjectFieldTemplate with left-border indent for nested objects
- Custom ArrayFieldTemplate with add/remove controls
- TextWidget, NumberWidget, CheckboxWidget, SelectWidget using @deco/ui
- PropEditor wrapper component rendering @rjsf/core Form
- Added @rjsf/core, @rjsf/utils, @rjsf/validator-ajv8, lucide-react deps

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../client/components/prop-editor.tsx         |  45 +++++
 .../client/components/rjsf/templates.tsx      | 167 ++++++++++++++++++
 .../client/components/rjsf/widgets.tsx        | 133 ++++++++++++++
 packages/mesh-plugin-site-editor/package.json |   4 +
 4 files changed, 349 insertions(+)
 create mode 100644 packages/mesh-plugin-site-editor/client/components/prop-editor.tsx
 create mode 100644 packages/mesh-plugin-site-editor/client/components/rjsf/templates.tsx
 create mode 100644 packages/mesh-plugin-site-editor/client/components/rjsf/widgets.tsx

diff --git a/packages/mesh-plugin-site-editor/client/components/prop-editor.tsx b/packages/mesh-plugin-site-editor/client/components/prop-editor.tsx
new file mode 100644
index 0000000000..be3f111415
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/components/prop-editor.tsx
@@ -0,0 +1,45 @@
+/**
+ * PropEditor Component
+ *
+ * Wraps @rjsf/core Form with custom CMS templates and widgets.
+ * Renders any JSON Schema as an editable form for block prop editing.
+ */
+
+import Form from "@rjsf/core";
+import type { RJSFSchema } from "@rjsf/utils";
+import validator from "@rjsf/validator-ajv8";
+import { customTemplates } from "./rjsf/templates";
+import { customWidgets } from "./rjsf/widgets";
+
+interface PropEditorProps {
+  schema: RJSFSchema;
+  formData: Record<string, unknown>;
+  onChange: (data: Record<string, unknown>) => void;
+  readonly?: boolean;
+}
+
+export function PropEditor({
+  schema,
+  formData,
+  onChange,
+  readonly,
+}: PropEditorProps) {
+  return (
+    <Form
+      schema={schema}
+      formData={formData}
+      onChange={(data) => onChange(data.formData ?? {})}
+      validator={validator}
+      widgets={customWidgets}
+      templates={customTemplates}
+      readonly={readonly}
+      uiSchema={{ "ui:submitButtonOptions": { norender: true } }}
+      liveValidate={false}
+      className="rjsf-form"
+      omitExtraData
+      liveOmit
+    >
+      <></>
+    </Form>
+  );
+}
diff --git a/packages/mesh-plugin-site-editor/client/components/rjsf/templates.tsx b/packages/mesh-plugin-site-editor/client/components/rjsf/templates.tsx
new file mode 100644
index 0000000000..6876e0c8f9
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/components/rjsf/templates.tsx
@@ -0,0 +1,167 @@
+/**
+ * Custom RJSF Templates for CMS Block Prop Editor
+ *
+ * Adapted from the Mesh workflow RJSF templates.
+ * Simplified for CMS use -- no mentions context, no workflow-specific features.
+ */
+
+import type {
+  FieldTemplateProps,
+  ObjectFieldTemplateProps,
+  ArrayFieldTemplateProps,
+  TemplatesType,
+} from "@rjsf/utils";
+import { Button } from "@deco/ui/components/button.tsx";
+import {
+  Type,
+  Hash,
+  Braces,
+  Box,
+  CheckSquare,
+  X,
+  FileText,
+} from "lucide-react";
+import { cn } from "@deco/ui/lib/utils.ts";
+
+function getTypeIcon(type: string | string[] | undefined) {
+  const typeStr = Array.isArray(type) ? type[0] : (type ?? "unknown");
+  switch (typeStr) {
+    case "string":
+      return { Icon: Type, color: "text-blue-500" };
+    case "number":
+    case "integer":
+      return { Icon: Hash, color: "text-blue-500" };
+    case "array":
+      return { Icon: Braces, color: "text-purple-500" };
+    case "object":
+      return { Icon: Box, color: "text-orange-500" };
+    case "boolean":
+      return { Icon: CheckSquare, color: "text-pink-500" };
+    case "null":
+      return { Icon: X, color: "text-gray-500" };
+    default:
+      return { Icon: FileText, color: "text-muted-foreground" };
+  }
+}
+
+/**
+ * Custom FieldTemplate - wraps each field with label, required indicator,
+ * description, and a type icon.
+ */
+function CustomFieldTemplate(props: FieldTemplateProps) {
+  const { id, label, required, description, children, schema, hidden } = props;
+
+  if (hidden) return <div className="hidden">{children}</div>;
+
+  // Root -- render children only (no label wrapper)
+  if (id === "root") {
+    return <div className="space-y-4">{children}</div>;
+  }
+
+  const schemaType = Array.isArray(schema.type)
+    ? schema.type[0]
+    : (schema.type ?? "string");
+  const { Icon, color } = getTypeIcon(schemaType);
+
+  return (
+    <div className="space-y-2">
+      <div className="flex items-center gap-2">
+        <label htmlFor={id} className="text-sm font-medium leading-none">
+          {label}
+        </label>
+        {required && <span className="text-red-500 text-xs">*</span>}
+        <Icon size={14} className={cn(color, "ml-auto")} />
+      </div>
+      {description && (
+        <div className="text-xs text-muted-foreground mb-1">{description}</div>
+      )}
+      {children}
+    </div>
+  );
+}
+
+/**
+ * Custom ObjectFieldTemplate - renders nested objects with a subtle left border indent.
+ * Shows object title if present.
+ */
+function CustomObjectFieldTemplate(props: ObjectFieldTemplateProps) {
+  const { properties, title } = props;
+  const isRoot = !title || title === "Root";
+
+  // Root object -- no wrapper
+  if (isRoot) {
+    return (
+      <div className="space-y-4">
+        {properties.map((prop) => (
+          <div key={prop.name}>{prop.content}</div>
+        ))}
+      </div>
+    );
+  }
+
+  // Nested object -- left border indent
+  return (
+    <div className="border-l-2 border-muted pl-3 space-y-4">
+      {properties.map((prop) => (
+        <div key={prop.name}>{prop.content}</div>
+      ))}
+    </div>
+  );
+}
+
+/**
+ * Custom ArrayFieldTemplate - renders array items with add/remove buttons.
+ * In @rjsf v6, items are ReactElements (already rendered with their own buttons).
+ */
+function CustomArrayFieldTemplate(props: ArrayFieldTemplateProps) {
+  const { items, canAdd, onAddClick, title } = props;
+
+  return (
+    <div className="space-y-2">
+      <div className="space-y-2">
+        {items.map((item, index) => (
+          <div
+            key={(item as any).key || index}
+            className="flex gap-2 items-start"
+          >
+            <div className="flex-1">{item}</div>
+          </div>
+        ))}
+      </div>
+      {canAdd && (
+        <Button
+          type="button"
+          variant="outline"
+          size="sm"
+          className="h-8"
+          onClick={onAddClick}
+        >
+          + Add {title || "item"}
+        </Button>
+      )}
+    </div>
+  );
+}
+
+/**
+ * Hides unsupported field errors
+ */
+function CustomUnsupportedFieldTemplate() {
+  return null;
+}
+
+/**
+ * Hides the error list at the top of the form
+ */
+function CustomErrorListTemplate() {
+  return null;
+}
+
+// Custom templates registry
+export const customTemplates: Partial<TemplatesType> = {
+  FieldTemplate: CustomFieldTemplate,
+  ObjectFieldTemplate: CustomObjectFieldTemplate,
+  ArrayFieldTemplate: CustomArrayFieldTemplate,
+  UnsupportedFieldTemplate: CustomUnsupportedFieldTemplate,
+  ErrorListTemplate: CustomErrorListTemplate,
+};
diff --git a/packages/mesh-plugin-site-editor/client/components/rjsf/widgets.tsx b/packages/mesh-plugin-site-editor/client/components/rjsf/widgets.tsx
new file mode 100644
index 0000000000..bd517eb45a
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/components/rjsf/widgets.tsx
@@ -0,0 +1,133 @@
+/**
+ * Custom RJSF Widgets for CMS Block Prop Editor
+ *
+ * Adapted from the Mesh workflow RJSF widgets.
+ * Uses @deco/ui components instead of workflow-specific MentionInput.
+ */
+
+import type { WidgetProps, RegistryWidgetsType } from "@rjsf/utils";
+import { Input } from "@deco/ui/components/input.tsx";
+import { Checkbox } from "@deco/ui/components/checkbox.tsx";
+import { cn } from "@deco/ui/lib/utils.ts";
+
+/**
+ * TextWidget - uses @deco/ui Input.
+ * Supports URL format and multiline via textarea fallback.
+ */
+function CustomTextWidget(props: WidgetProps) {
+  const { value, onChange, placeholder, readonly, id, schema } = props;
+
+  const isUrl = schema.format === "uri" || schema.format === "url";
+  const isMultiline =
+    (schema as Record<string, unknown>)["ui:widget"] === "textarea" ||
+    (typeof schema.description === "string" &&
+      schema.description.toLowerCase().includes("multiline"));
+
+  if (isMultiline) {
+    return (
+      <textarea
+        id={id}
+        value={value ?? ""}
+        onChange={(e) => onChange(e.target.value || undefined)}
+        placeholder={placeholder || "Enter value..."}
+        disabled={readonly}
+        rows={4}
+        className={cn(
+          "w-full rounded-md border border-input bg-background px-3 py-2 text-sm",
+          "ring-offset-background focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2",
+          "disabled:cursor-not-allowed disabled:opacity-50",
+          "resize-y min-h-[80px]",
+        )}
+      />
+    );
+  }
+
+  return (
+    <Input
+      id={id}
+      type={isUrl ? "url" : "text"}
+      value={value ?? ""}
+      onChange={(e) => onChange(e.target.value || undefined)}
+      placeholder={placeholder || "Enter value..."}
+      disabled={readonly}
+    />
+  );
+}
+
+/**
+ * NumberWidget - uses @deco/ui Input with type="number".
+ * Handles min/max from schema.
+ */
+function CustomNumberWidget(props: WidgetProps) {
+  const { value, onChange, readonly, id, schema } = props;
+
+  return (
+    <Input
+      id={id}
+      type="number"
+      value={value ?? ""}
+      onChange={(e) =>
+        onChange(e.target.value === "" ? undefined : Number(e.target.value))
+      }
+      min={schema.minimum}
+      max={schema.maximum}
+      disabled={readonly}
+    />
+  );
+}
+
+/**
+ * CheckboxWidget - uses @deco/ui Checkbox with label.
+ */
+function CustomCheckboxWidget(props: WidgetProps) {
+  const { value, onChange, readonly, id, label } = props;
+
+  return (
+    <label htmlFor={id} className="flex items-center gap-2 cursor-pointer">
+      <Checkbox
+        id={id}
+        checked={value ?? false}
+        onCheckedChange={(checked) => onChange(checked)}
+        disabled={readonly}
+      />
+      <span className="text-sm">{label}</span>
+    </label>
+  );
+}
+
+/**
+ * SelectWidget - renders enum values as a native select.
+ */
+function CustomSelectWidget(props: WidgetProps) {
+  const { value, onChange, readonly, id, options } = props;
+  const enumOptions = options.enumOptions ?? [];
+
+  return (
+    <select
+      id={id}
+      value={value ?? ""}
+      onChange={(e) => onChange(e.target.value)}
+      disabled={readonly}
+      className={cn(
+        "w-full rounded-md border border-input bg-background px-3 py-2 text-sm",
+        "ring-offset-background focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2",
+        "disabled:cursor-not-allowed disabled:opacity-50",
+      )}
+    >
+      <option value="">Select...</option>
+      {enumOptions.map((opt) => (
+        <option key={String(opt.value)} value={String(opt.value)}>
+          {String(opt.label)}
+        </option>
+      ))}
+    </select>
+  );
+}
+
+// Custom widgets registry
+export const customWidgets: RegistryWidgetsType = {
+  TextWidget: CustomTextWidget,
+  NumberWidget: CustomNumberWidget,
+  CheckboxWidget: CustomCheckboxWidget,
+  SelectWidget: CustomSelectWidget,
+};
diff --git a/packages/mesh-plugin-site-editor/package.json b/packages/mesh-plugin-site-editor/package.json
index 2a127d9e5f..84eb226a8c 100644
--- a/packages/mesh-plugin-site-editor/package.json
+++ b/packages/mesh-plugin-site-editor/package.json
@@ -15,7 +15,11 @@
     "@decocms/bindings": "workspace:*",
     "@decocms/mesh-sdk": "workspace:*",
     "@deco/ui": "workspace:*",
+    "@rjsf/core": "^6.1.2",
+    "@rjsf/utils": "^6.1.2",
+    "@rjsf/validator-ajv8": "^6.1.2",
     "@untitledui/icons": "^0.0.19",
+    "lucide-react": "^0.468.0",
     "ts-morph": "^27.0.2",
     "ts-json-schema-generator": "^2.4.0",
     "zod": "^4.0.0"

From ffc6d9348f691295a62e1392c1883ec57502311d Mon Sep 17 00:00:00 2001
From: Guilherme Rodrigues <gui@deco.cx>
Date: Sat, 14 Feb 2026 10:10:14 -0300
Subject: [PATCH 09/26] feat(02-02): add block list UI, block detail view, and
 routing

- SectionsList: block browser grouped by category with empty state
- BlockDetail: metadata display, collapsible JSON Schema, PropEditor form
- Router: added /sections/$blockId route for block detail navigation
- Block list fetches via listBlocks from block-api with React Query
- Block detail uses ref-based formData sync pattern (no useEffect)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../client/components/block-detail.tsx        | 234 ++++++++++++++++++
 .../client/components/sections-list.tsx       | 150 ++++++++++-
 .../client/lib/router.ts                      |  14 +-
 3 files changed, 389 insertions(+), 9 deletions(-)
 create mode 100644 packages/mesh-plugin-site-editor/client/components/block-detail.tsx

diff --git a/packages/mesh-plugin-site-editor/client/components/block-detail.tsx b/packages/mesh-plugin-site-editor/client/components/block-detail.tsx
new file mode 100644
index 0000000000..b5e546acb8
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/components/block-detail.tsx
@@ -0,0 +1,234 @@
+/**
+ * Block Detail Component
+ *
+ * Shows block metadata and an @rjsf prop editor form.
+ * Uses SITE_BINDING tools via block-api helpers.
+ * Local formData state only -- Phase 3 will wire saves to page block instances.
+ */
+
+import { useRef, useState } from "react";
+import { SITE_BINDING } from "@decocms/bindings/site";
+import { usePluginContext } from "@decocms/mesh-sdk/plugins";
+import { useQuery } from "@tanstack/react-query";
+import { Button } from "@deco/ui/components/button.tsx";
+import { Badge } from "@deco/ui/components/badge.tsx";
+import { ArrowLeft, Loading01, AlertCircle } from "@untitledui/icons";
+import { ChevronDown, ChevronRight } from "lucide-react";
+import { blockKeys } from "../lib/query-keys";
+import { siteEditorRouter } from "../lib/router";
+import { getBlock } from "../lib/block-api";
+import { PropEditor } from "./prop-editor";
+
+function formatTimestamp(dateStr: string): string {
+  if (!dateStr) return "-";
+  try {
+    return new Date(dateStr).toLocaleString(undefined, {
+      year: "numeric",
+      month: "short",
+      day: "numeric",
+      hour: "2-digit",
+      minute: "2-digit",
+    });
+  } catch {
+    return dateStr;
+  }
+}
+
+function scanMethodLabel(method: string): string {
+  switch (method) {
+    case "ts-morph":
+      return "ts-morph";
+    case "manual":
+      return "Manual";
+    case "ai-agent":
+      return "AI Agent";
+    default:
+      return method;
+  }
+}
+
+export default function BlockDetail() {
+  const { toolCaller, connectionId } = usePluginContext<typeof SITE_BINDING>();
+  const navigate = siteEditorRouter.useNavigate();
+  const { blockId } = siteEditorRouter.useParams({
+    from: "/sections/$blockId",
+  });
+
+  const [formData, setFormData] = useState<Record<string, unknown>>({});
+  const [schemaExpanded, setSchemaExpanded] = useState(false);
+  const lastSyncedBlockId = useRef<string | null>(null);
+
+  const {
+    data: block,
+    isLoading,
+    error,
+  } = useQuery({
+    queryKey: blockKeys.detail(connectionId, blockId),
+    queryFn: () => getBlock(toolCaller, blockId),
+  });
+
+  // Sync formData when block data loads (ref-based, not useEffect)
+  if (block && lastSyncedBlockId.current !== block.id) {
+    lastSyncedBlockId.current = block.id;
+    setFormData(block.defaults ?? {});
+  }
+
+  if (isLoading) {
+    return (
+      <div className="flex flex-col items-center justify-center h-full p-8">
+        <Loading01
+          size={32}
+          className="animate-spin text-muted-foreground mb-4"
+        />
+        <p className="text-sm text-muted-foreground">Loading block...</p>
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className="flex flex-col items-center justify-center h-full p-8">
+        <AlertCircle size={48} className="text-destructive mb-4" />
+        <h3 className="text-lg font-medium mb-2">Error loading block</h3>
+        <p className="text-muted-foreground text-center">
+          {error instanceof Error ? error.message : "Unknown error"}
+        </p>
+      </div>
+    );
+  }
+
+  if (!block) {
+    return (
+      <div className="flex flex-col items-center justify-center h-full p-8">
+        <AlertCircle size={48} className="text-muted-foreground mb-4" />
+        <h3 className="text-lg font-medium mb-2">Block not found</h3>
+        <p className="text-muted-foreground text-center mb-4">
+          The block "{blockId}" could not be found.
+        </p>
+        <Button variant="outline" onClick={() => navigate({ to: "/sections" })}>
+          <ArrowLeft size={14} className="mr-1" />
+          Back to Sections
+        </Button>
+      </div>
+    );
+  }
+
+  const propsCount = Object.keys(block.schema?.properties ?? {}).length;
+  const hasSchema =
+    block.schema &&
+    typeof block.schema === "object" &&
+    Object.keys(block.schema).length > 0;
+
+  return (
+    <div className="flex flex-col h-full">
+      {/* Header with breadcrumb */}
+      <div className="flex items-center justify-between px-4 py-3 border-b border-border bg-background">
+        <div className="flex items-center gap-2 text-sm">
+          <button
+            type="button"
+            onClick={() => navigate({ to: "/sections" })}
+            className="text-muted-foreground hover:text-foreground transition-colors"
+          >
+            Sections
+          </button>
+          <span className="text-muted-foreground">/</span>
+          <span className="font-medium">{block.label}</span>
+        </div>
+      </div>
+
+      {/* Content */}
+      <div className="flex-1 overflow-y-auto p-6">
+        <div className="max-w-2xl space-y-6">
+          {/* Block info */}
+          <div>
+            <h2 className="text-xl font-semibold">{block.label}</h2>
+            <p className="text-sm text-muted-foreground mt-1">
+              {block.component}
+            </p>
+            {block.description && (
+              <p className="text-sm text-muted-foreground mt-2">
+                {block.description}
+              </p>
+            )}
+          </div>
+
+          {/* Metadata section */}
+          <div className="border border-border rounded-lg p-4 space-y-3">
+            <h3 className="text-sm font-medium text-muted-foreground">
+              Metadata
+            </h3>
+            <div className="grid grid-cols-2 gap-3 text-sm">
+              <div>
+                <span className="text-muted-foreground">Scan Method</span>
+                <div className="mt-0.5">
+                  <Badge variant="secondary" className="text-xs">
+                    {scanMethodLabel(block.metadata.scanMethod)}
+                  </Badge>
+                </div>
+              </div>
+              <div>
+                <span className="text-muted-foreground">Scanned</span>
+                <p className="mt-0.5">
+                  {formatTimestamp(block.metadata.scannedAt)}
+                </p>
+              </div>
+              <div>
+                <span className="text-muted-foreground">Props Type</span>
+                <p className="font-mono text-xs mt-0.5">
+                  {block.metadata.propsTypeName ?? "unknown"}
+                </p>
+              </div>
+              <div>
+                <span className="text-muted-foreground">Properties</span>
+                <p className="mt-0.5">{propsCount} props</p>
+              </div>
+            </div>
+          </div>
+
+          {/* Raw schema (collapsible) */}
+          {hasSchema && (
+            <div className="border border-border rounded-lg">
+              <button
+                type="button"
+                onClick={() => setSchemaExpanded(!schemaExpanded)}
+                className="flex items-center gap-2 w-full px-4 py-3 text-sm font-medium text-muted-foreground hover:text-foreground transition-colors"
+              >
+                {schemaExpanded ? (
+                  <ChevronDown size={14} />
+                ) : (
+                  <ChevronRight size={14} />
+                )}
+                Raw JSON Schema
+              </button>
+              {schemaExpanded && (
+                <div className="border-t border-border px-4 py-3">
+                  <pre className="text-xs font-mono overflow-x-auto bg-muted/30 rounded p-3 max-h-80 overflow-y-auto">
+                    {JSON.stringify(block.schema, null, 2)}
+                  </pre>
+                </div>
+              )}
+            </div>
+          )}
+
+          {/* Props editor */}
+          {hasSchema ? (
+            <div className="space-y-3">
+              <h3 className="text-sm font-medium">Props Editor</h3>
+              <div className="border border-border rounded-lg p-4">
+                <PropEditor
+                  schema={block.schema as any}
+                  formData={formData}
+                  onChange={setFormData}
+                />
+              </div>
+            </div>
+          ) : (
+            <div className="text-center py-8 text-muted-foreground text-sm">
+              No schema available for this block.
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/packages/mesh-plugin-site-editor/client/components/sections-list.tsx b/packages/mesh-plugin-site-editor/client/components/sections-list.tsx
index f857c8776b..68506979ae 100644
--- a/packages/mesh-plugin-site-editor/client/components/sections-list.tsx
+++ b/packages/mesh-plugin-site-editor/client/components/sections-list.tsx
@@ -1,17 +1,151 @@
 /**
- * Sections List Component
+ * Sections List Component (Block Browser)
  *
- * Displays the list of sections managed by the site editor.
- * Full implementation will be added in later plans.
+ * Displays all scanned blocks grouped by category.
+ * Navigates to block detail view on click.
+ * Uses SITE_BINDING tools (LIST_FILES, READ_FILE) via block-api helpers.
  */
 
+import { SITE_BINDING } from "@decocms/bindings/site";
+import { usePluginContext } from "@decocms/mesh-sdk/plugins";
+import { useQuery } from "@tanstack/react-query";
+import { Button } from "@deco/ui/components/button.tsx";
+import { Badge } from "@deco/ui/components/badge.tsx";
+import { AlertCircle, Loading01 } from "@untitledui/icons";
+import { Box, Search } from "lucide-react";
+import { blockKeys } from "../lib/query-keys";
+import { siteEditorRouter } from "../lib/router";
+import { listBlocks } from "../lib/block-api";
+import type { BlockSummary } from "../lib/block-api";
+
+/**
+ * Group blocks by category, sorted alphabetically within each group.
+ */
+function groupByCategory(
+  blocks: BlockSummary[],
+): Record<string, BlockSummary[]> {
+  const groups: Record<string, BlockSummary[]> = {};
+  for (const block of blocks) {
+    const category = block.category || "Other";
+    if (!groups[category]) {
+      groups[category] = [];
+    }
+    groups[category].push(block);
+  }
+  // Sort blocks within each category
+  for (const category of Object.keys(groups)) {
+    groups[category].sort((a, b) => a.label.localeCompare(b.label));
+  }
+  return groups;
+}
+
 export default function SectionsList() {
+  const { toolCaller, connectionId } = usePluginContext<typeof SITE_BINDING>();
+  const navigate = siteEditorRouter.useNavigate();
+
+  const {
+    data: blocks = [],
+    isLoading,
+    error,
+  } = useQuery({
+    queryKey: blockKeys.all(connectionId),
+    queryFn: () => listBlocks(toolCaller),
+  });
+
+  if (error) {
+    return (
+      <div className="flex flex-col items-center justify-center h-full p-8">
+        <AlertCircle size={48} className="text-destructive mb-4" />
+        <h3 className="text-lg font-medium mb-2">Error loading blocks</h3>
+        <p className="text-muted-foreground text-center">
+          {error instanceof Error ? error.message : "Unknown error"}
+        </p>
+      </div>
+    );
+  }
+
+  const grouped = groupByCategory(blocks);
+  const categoryNames = Object.keys(grouped).sort();
+
   return (
-    <div className="flex flex-col items-center justify-center h-full p-8">
-      <h3 className="text-lg font-medium mb-2">Sections</h3>
-      <p className="text-muted-foreground text-center max-w-md">
-        Sections will appear here once file listing is implemented.
-      </p>
+    <div className="flex flex-col h-full">
+      {/* Header */}
+      <div className="flex items-center justify-between px-4 py-3 border-b border-border bg-background">
+        <h2 className="text-sm font-medium">Sections</h2>
+        <Badge variant="secondary" className="text-xs">
+          {blocks.length} blocks
+        </Badge>
+      </div>
+
+      {/* Block list */}
+      <div className="flex-1 overflow-y-auto">
+        {isLoading ? (
+          <div className="flex flex-col items-center justify-center py-12">
+            <Loading01
+              size={32}
+              className="animate-spin text-muted-foreground mb-4"
+            />
+            <p className="text-sm text-muted-foreground">Loading blocks...</p>
+          </div>
+        ) : blocks.length === 0 ? (
+          <div className="flex flex-col items-center justify-center py-12 text-center px-6">
+            <Search size={48} className="text-muted-foreground mb-4" />
+            <h3 className="text-lg font-medium mb-2">No blocks found</h3>
+            <p className="text-muted-foreground mb-4 max-w-sm">
+              Scan your codebase to discover React components and generate
+              editable prop forms automatically.
+            </p>
+            <Button
+              variant="outline"
+              onClick={() => {
+                console.log(
+                  "[site-editor] Scan trigger placeholder -- wire to CMS_BLOCK_SCAN in Phase 3",
+                );
+              }}
+            >
+              <Search size={14} className="mr-1" />
+              Scan Codebase
+            </Button>
+          </div>
+        ) : (
+          categoryNames.map((category) => (
+            <div key={category}>
+              {/* Category header */}
+              <div className="px-4 py-2 text-xs font-medium text-muted-foreground uppercase tracking-wider bg-muted/30 border-b border-border">
+                {category}
+              </div>
+
+              {/* Blocks in category */}
+              {grouped[category].map((block) => (
+                <button
+                  key={block.id}
+                  type="button"
+                  onClick={() =>
+                    navigate({
+                      to: "/sections/$blockId",
+                      params: { blockId: block.id },
+                    })
+                  }
+                  className="group flex items-center gap-3 px-4 py-2.5 w-full text-left hover:bg-muted/50 border-b border-border last:border-b-0 transition-colors"
+                >
+                  <Box size={16} className="text-muted-foreground shrink-0" />
+                  <div className="flex-1 min-w-0">
+                    <span className="truncate font-medium text-sm block">
+                      {block.label}
+                    </span>
+                    <span className="text-xs text-muted-foreground truncate block">
+                      {block.component}
+                    </span>
+                  </div>
+                  <Badge variant="outline" className="text-xs shrink-0">
+                    {block.propsCount} props
+                  </Badge>
+                </button>
+              ))}
+            </div>
+          ))
+        )}
+      </div>
     </div>
   );
 }
diff --git a/packages/mesh-plugin-site-editor/client/lib/router.ts b/packages/mesh-plugin-site-editor/client/lib/router.ts
index 100cdff02a..423f6a14e7 100644
--- a/packages/mesh-plugin-site-editor/client/lib/router.ts
+++ b/packages/mesh-plugin-site-editor/client/lib/router.ts
@@ -31,11 +31,23 @@ export const siteEditorRouter = createPluginRouter((ctx) => {
     component: lazyRouteComponent(() => import("../components/sections-list")),
   });
 
+  const blockDetailRoute = createRoute({
+    getParentRoute: () => ctx.parentRoute,
+    path: "/sections/$blockId",
+    component: lazyRouteComponent(() => import("../components/block-detail")),
+  });
+
   const loadersRoute = createRoute({
     getParentRoute: () => ctx.parentRoute,
     path: "/loaders",
     component: lazyRouteComponent(() => import("../components/loaders-list")),
   });
 
-  return [pagesRoute, pageEditorRoute, sectionsRoute, loadersRoute];
+  return [
+    pagesRoute,
+    pageEditorRoute,
+    sectionsRoute,
+    blockDetailRoute,
+    loadersRoute,
+  ];
 });

From 8668b2f004049044425e3505dab22bde429f769b Mon Sep 17 00:00:00 2001
From: Guilherme Rodrigues <gui@deco.cx>
Date: Sat, 14 Feb 2026 10:27:55 -0300
Subject: [PATCH 10/26] feat(03-01): typed postMessage protocol and
 BlockInstance type

- Add editor-protocol.ts with EditorMessage/SiteMessage discriminated unions
- Add use-editor-messages.ts hook with send/subscribe and source filtering
- Add BlockInstance interface to page-api.ts replacing unknown[] in Page.blocks

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../client/lib/editor-protocol.ts             | 36 +++++++++++++++
 .../client/lib/page-api.ts                    | 13 +++++-
 .../client/lib/use-editor-messages.ts         | 44 +++++++++++++++++++
 3 files changed, 91 insertions(+), 2 deletions(-)
 create mode 100644 packages/mesh-plugin-site-editor/client/lib/editor-protocol.ts
 create mode 100644 packages/mesh-plugin-site-editor/client/lib/use-editor-messages.ts

diff --git a/packages/mesh-plugin-site-editor/client/lib/editor-protocol.ts b/packages/mesh-plugin-site-editor/client/lib/editor-protocol.ts
new file mode 100644
index 0000000000..3ed3fb0165
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/lib/editor-protocol.ts
@@ -0,0 +1,36 @@
+/**
+ * Editor Protocol
+ *
+ * Typed postMessage protocol for communication between the Mesh editor
+ * and the site iframe. Uses discriminated unions for type-safe message
+ * handling with a "deco:" prefix to filter from other messages.
+ */
+
+import type { Page } from "./page-api";
+
+/** Prefix for all deco editor messages */
+export const DECO_MSG_PREFIX = "deco:" as const;
+
+/**
+ * Messages sent from the Mesh editor to the site iframe.
+ */
+export type EditorMessage =
+  | { type: "deco:page-config"; page: Page }
+  | {
+      type: "deco:update-block";
+      blockId: string;
+      props: Record<string, unknown>;
+    }
+  | { type: "deco:select-block"; blockId: string }
+  | { type: "deco:set-viewport"; width: number };
+
+/**
+ * Messages sent from the site iframe to the Mesh editor.
+ */
+export type SiteMessage =
+  | { type: "deco:ready"; version: number }
+  | { type: "deco:block-clicked"; blockId: string; rect: DOMRect }
+  | {
+      type: "deco:blocks-rendered";
+      blocks: Array<{ id: string; rect: DOMRect }>;
+    };
diff --git a/packages/mesh-plugin-site-editor/client/lib/page-api.ts b/packages/mesh-plugin-site-editor/client/lib/page-api.ts
index febb025885..ef39cb05e9 100644
--- a/packages/mesh-plugin-site-editor/client/lib/page-api.ts
+++ b/packages/mesh-plugin-site-editor/client/lib/page-api.ts
@@ -19,11 +19,20 @@ export interface PageSummary {
   updatedAt: string;
 }
 
+export interface BlockInstance {
+  /** Unique ID for this block instance on the page */
+  id: string;
+  /** Reference to block definition in .deco/blocks/ (e.g., "sections--Hero") */
+  blockType: string;
+  /** User-edited props for this instance */
+  props: Record<string, unknown>;
+}
+
 export interface Page {
   id: string;
   path: string;
   title: string;
-  blocks: unknown[];
+  blocks: BlockInstance[];
   metadata: {
     description: string;
     createdAt: string;
@@ -132,7 +141,7 @@ export async function createPage(
 export async function updatePage(
   toolCaller: ToolCaller,
   pageId: string,
-  updates: { title?: string; path?: string; blocks?: unknown[] },
+  updates: { title?: string; path?: string; blocks?: BlockInstance[] },
 ): Promise<Page> {
   const result = await toolCaller("READ_FILE", {
     path: `${PAGES_PREFIX}${pageId}.json`,
diff --git a/packages/mesh-plugin-site-editor/client/lib/use-editor-messages.ts b/packages/mesh-plugin-site-editor/client/lib/use-editor-messages.ts
new file mode 100644
index 0000000000..141c11bd8e
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/lib/use-editor-messages.ts
@@ -0,0 +1,44 @@
+/**
+ * useEditorMessages Hook
+ *
+ * Provides typed send/subscribe for the editor-iframe postMessage protocol.
+ * Filters messages by source (iframe contentWindow) and prefix ("deco:").
+ */
+
+import type { RefObject } from "react";
+import type { EditorMessage, SiteMessage } from "./editor-protocol";
+import { DECO_MSG_PREFIX } from "./editor-protocol";
+
+interface UseEditorMessagesResult {
+  /** Send a typed message to the iframe */
+  send: (msg: EditorMessage) => void;
+  /** Subscribe to typed messages from the iframe. Returns cleanup function. */
+  subscribe: (handler: (msg: SiteMessage) => void) => () => void;
+}
+
+/**
+ * Hook for typed postMessage communication with the site iframe.
+ *
+ * Uses "*" as targetOrigin because the tunnel URL is cross-origin.
+ * Filters incoming messages by source (iframe contentWindow) and
+ * prefix ("deco:") to ignore unrelated messages.
+ */
+export function useEditorMessages(
+  iframeRef: RefObject<HTMLIFrameElement | null>,
+): UseEditorMessagesResult {
+  const send = (msg: EditorMessage) => {
+    iframeRef.current?.contentWindow?.postMessage(msg, "*");
+  };
+
+  const subscribe = (handler: (msg: SiteMessage) => void) => {
+    const listener = (e: MessageEvent) => {
+      if (e.source !== iframeRef.current?.contentWindow) return;
+      if (!e.data?.type?.startsWith(DECO_MSG_PREFIX)) return;
+      handler(e.data as SiteMessage);
+    };
+    window.addEventListener("message", listener);
+    return () => window.removeEventListener("message", listener);
+  };
+
+  return { send, subscribe };
+}

From f48f5c75a7b99a05fbdb4205a578cd29494394c0 Mon Sep 17 00:00:00 2001
From: Guilherme Rodrigues <gui@deco.cx>
Date: Sat, 14 Feb 2026 10:32:53 -0300
Subject: [PATCH 11/26] feat(03-01): page composer layout, viewport toggle, and
 enhanced preview panel

- Add viewport-toggle.tsx with mobile/tablet/desktop at 375/768/1440px
- Rewrite preview-panel.tsx with postMessage protocol via useIframeBridge
- Add use-iframe-bridge.ts using useSyncExternalStore for ready state
- Add page-composer.tsx three-panel layout with section list, preview, prop editor

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../client/components/page-composer.tsx       | 276 ++++++++++++++++++
 .../client/components/preview-panel.tsx       |  38 ++-
 .../client/components/viewport-toggle.tsx     |  44 +++
 .../client/lib/use-iframe-bridge.ts           | 139 +++++++++
 4 files changed, 490 insertions(+), 7 deletions(-)
 create mode 100644 packages/mesh-plugin-site-editor/client/components/page-composer.tsx
 create mode 100644 packages/mesh-plugin-site-editor/client/components/viewport-toggle.tsx
 create mode 100644 packages/mesh-plugin-site-editor/client/lib/use-iframe-bridge.ts

diff --git a/packages/mesh-plugin-site-editor/client/components/page-composer.tsx b/packages/mesh-plugin-site-editor/client/components/page-composer.tsx
new file mode 100644
index 0000000000..924c3431b8
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/components/page-composer.tsx
@@ -0,0 +1,276 @@
+/**
+ * Page Composer Component
+ *
+ * Three-panel visual editor layout:
+ * - Left: section list sidebar (placeholder for Plan 03-02)
+ * - Center: iframe preview with viewport toggle
+ * - Right: prop editor for selected block
+ *
+ * Fetches page data, manages selected block state, and wires postMessage
+ * communication for live preview updates.
+ */
+
+import { useRef, useState } from "react";
+import { SITE_BINDING } from "@decocms/bindings/site";
+import { usePluginContext } from "@decocms/mesh-sdk/plugins";
+import { useQuery } from "@tanstack/react-query";
+import { Button } from "@deco/ui/components/button.tsx";
+import { cn } from "@deco/ui/lib/utils.ts";
+import { ArrowLeft, Save01, Loading01, AlertCircle } from "@untitledui/icons";
+import { toast } from "sonner";
+import { queryKeys } from "../lib/query-keys";
+import { siteEditorRouter } from "../lib/router";
+import { getPage, updatePage, type Page } from "../lib/page-api";
+import { getBlock } from "../lib/block-api";
+import { useEditorMessages } from "../lib/use-editor-messages";
+import { PreviewPanel } from "./preview-panel";
+import { ViewportToggle, type ViewportKey } from "./viewport-toggle";
+import { PropEditor } from "./prop-editor";
+
+export default function PageComposer() {
+  const { toolCaller, connectionId } = usePluginContext<typeof SITE_BINDING>();
+  const navigate = siteEditorRouter.useNavigate();
+  const { pageId } = siteEditorRouter.useParams({ from: "/pages/$pageId" });
+
+  const [selectedBlockId, setSelectedBlockId] = useState<string | null>(null);
+  const [viewport, setViewport] = useState<ViewportKey>("desktop");
+  const [localPage, setLocalPage] = useState<Page | null>(null);
+  const saveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+  const { send } = useEditorMessages(iframeRef);
+
+  // Fetch page data
+  const {
+    data: page,
+    isLoading,
+    error,
+  } = useQuery({
+    queryKey: queryKeys.pages.detail(connectionId, pageId),
+    queryFn: () => getPage(toolCaller, pageId),
+  });
+
+  // Sync local page copy when server data loads
+  const lastSyncedRef = useRef<string | null>(null);
+  if (page && lastSyncedRef.current !== page.metadata.updatedAt) {
+    lastSyncedRef.current = page.metadata.updatedAt;
+    setLocalPage(page);
+  }
+
+  // Find selected block
+  const selectedBlock = localPage?.blocks.find((b) => b.id === selectedBlockId);
+
+  // Fetch block definition (schema) for the selected block
+  const { data: blockDef } = useQuery({
+    queryKey: queryKeys.blocks.detail(
+      connectionId,
+      selectedBlock?.blockType ?? "",
+    ),
+    queryFn: () => getBlock(toolCaller, selectedBlock!.blockType),
+    enabled: !!selectedBlock,
+  });
+
+  // Debounced save to git
+  const debouncedSave = (updatedPage: Page) => {
+    if (saveTimerRef.current) {
+      clearTimeout(saveTimerRef.current);
+    }
+    saveTimerRef.current = setTimeout(async () => {
+      try {
+        await updatePage(toolCaller, pageId, {
+          blocks: updatedPage.blocks,
+        });
+      } catch (err) {
+        toast.error(
+          `Failed to save: ${err instanceof Error ? err.message : "Unknown error"}`,
+        );
+      }
+    }, 2000);
+  };
+
+  // Handle prop changes from PropEditor
+  const handlePropChange = (newProps: Record<string, unknown>) => {
+    if (!localPage || !selectedBlockId) return;
+
+    const updatedBlocks = localPage.blocks.map((block) =>
+      block.id === selectedBlockId ? { ...block, props: newProps } : block,
+    );
+
+    const updatedPage: Page = {
+      ...localPage,
+      blocks: updatedBlocks,
+    };
+
+    setLocalPage(updatedPage);
+
+    // Immediately send to iframe for live preview
+    send({
+      type: "deco:update-block",
+      blockId: selectedBlockId,
+      props: newProps,
+    });
+
+    // Debounce save to git
+    debouncedSave(updatedPage);
+  };
+
+  // Manual save
+  const handleSave = async () => {
+    if (!localPage) return;
+    if (saveTimerRef.current) {
+      clearTimeout(saveTimerRef.current);
+      saveTimerRef.current = null;
+    }
+    try {
+      await updatePage(toolCaller, pageId, {
+        title: localPage.title,
+        path: localPage.path,
+        blocks: localPage.blocks,
+      });
+      toast.success("Page saved");
+    } catch (err) {
+      toast.error(
+        `Failed to save: ${err instanceof Error ? err.message : "Unknown error"}`,
+      );
+    }
+  };
+
+  if (isLoading) {
+    return (
+      <div className="flex flex-col items-center justify-center h-full p-8">
+        <Loading01
+          size={32}
+          className="animate-spin text-muted-foreground mb-4"
+        />
+        <p className="text-sm text-muted-foreground">Loading page...</p>
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className="flex flex-col items-center justify-center h-full p-8">
+        <AlertCircle size={48} className="text-destructive mb-4" />
+        <h3 className="text-lg font-medium mb-2">Error loading page</h3>
+        <p className="text-muted-foreground text-center">
+          {error instanceof Error ? error.message : "Unknown error"}
+        </p>
+      </div>
+    );
+  }
+
+  if (!localPage) {
+    return (
+      <div className="flex flex-col items-center justify-center h-full p-8">
+        <AlertCircle size={48} className="text-muted-foreground mb-4" />
+        <h3 className="text-lg font-medium mb-2">Page not found</h3>
+        <p className="text-muted-foreground text-center mb-4">
+          The page &quot;{pageId}&quot; could not be found.
+        </p>
+        <Button variant="outline" onClick={() => navigate({ to: "/" })}>
+          <ArrowLeft size={14} className="mr-1" />
+          Back to Pages
+        </Button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="flex flex-col h-full">
+      {/* Top bar: breadcrumb, save button, viewport toggle */}
+      <div className="flex items-center justify-between px-4 py-2 border-b border-border bg-background">
+        <div className="flex items-center gap-2 text-sm">
+          <button
+            type="button"
+            onClick={() => navigate({ to: "/" })}
+            className="text-muted-foreground hover:text-foreground transition-colors"
+          >
+            Pages
+          </button>
+          <span className="text-muted-foreground">/</span>
+          <span className="font-medium">{localPage.title}</span>
+        </div>
+
+        <div className="flex items-center gap-3">
+          <ViewportToggle value={viewport} onChange={setViewport} />
+          <Button size="sm" onClick={handleSave}>
+            <Save01 size={14} className="mr-1" />
+            Save
+          </Button>
+        </div>
+      </div>
+
+      {/* Three-panel layout */}
+      <div className="flex flex-1 overflow-hidden">
+        {/* Left panel: section list (placeholder for Plan 03-02) */}
+        <div className="w-[260px] border-r border-border overflow-y-auto p-4">
+          <h3 className="text-sm font-medium text-muted-foreground mb-3">
+            Sections
+          </h3>
+          {localPage.blocks.length === 0 ? (
+            <p className="text-xs text-muted-foreground">
+              No sections yet. Add sections in Plan 03-02.
+            </p>
+          ) : (
+            <div className="space-y-1">
+              {localPage.blocks.map((block) => (
+                <button
+                  key={block.id}
+                  type="button"
+                  onClick={() => setSelectedBlockId(block.id)}
+                  className={cn(
+                    "w-full text-left px-3 py-2 rounded text-sm transition-colors",
+                    selectedBlockId === block.id
+                      ? "bg-accent text-accent-foreground"
+                      : "hover:bg-muted",
+                  )}
+                >
+                  {block.blockType.replace("sections--", "")}
+                </button>
+              ))}
+            </div>
+          )}
+        </div>
+
+        {/* Center panel: preview */}
+        <div className="flex-1 overflow-hidden">
+          <PreviewPanel
+            path={localPage.path}
+            page={localPage}
+            selectedBlockId={selectedBlockId}
+            viewport={viewport}
+            onBlockClicked={setSelectedBlockId}
+          />
+        </div>
+
+        {/* Right panel: prop editor */}
+        <div className="w-[320px] border-l border-border overflow-y-auto">
+          {selectedBlock && blockDef?.schema ? (
+            <div className="p-4">
+              <h3 className="text-sm font-medium mb-3">
+                {blockDef.label ??
+                  selectedBlock.blockType.replace("sections--", "")}
+              </h3>
+              <PropEditor
+                schema={blockDef.schema as import("@rjsf/utils").RJSFSchema}
+                formData={selectedBlock.props}
+                onChange={handlePropChange}
+              />
+            </div>
+          ) : selectedBlockId ? (
+            <div className="flex items-center justify-center h-full p-4">
+              <p className="text-sm text-muted-foreground">
+                Loading block schema...
+              </p>
+            </div>
+          ) : (
+            <div className="flex items-center justify-center h-full p-4">
+              <p className="text-sm text-muted-foreground">
+                Select a section to edit
+              </p>
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/packages/mesh-plugin-site-editor/client/components/preview-panel.tsx b/packages/mesh-plugin-site-editor/client/components/preview-panel.tsx
index 4fa3c70e53..140e2aa173 100644
--- a/packages/mesh-plugin-site-editor/client/components/preview-panel.tsx
+++ b/packages/mesh-plugin-site-editor/client/components/preview-panel.tsx
@@ -2,22 +2,43 @@
  * Preview Panel Component
  *
  * Renders a full-size iframe pointing to the user's running local dev server
- * via the tunnel URL created by `deco link`. When no tunnel URL is available,
- * shows a helpful empty state with instructions.
+ * via the tunnel URL. Communicates with the iframe via a typed postMessage
+ * protocol (deco:ready handshake, deco:page-config, deco:select-block).
  *
- * This component fills its parent container (100% width and height).
- * Responsive viewport toggles will be added in Phase 3 (EDIT-04).
+ * Supports viewport width switching for responsive preview.
  */
 
 import { useTunnelUrl } from "../lib/use-tunnel-url";
+import { useIframeBridge } from "../lib/use-iframe-bridge";
+import { VIEWPORTS, type ViewportKey } from "./viewport-toggle";
+import type { Page } from "../lib/page-api";
 
 interface PreviewPanelProps {
   /** Page path to preview (e.g., "/", "/about") */
   path?: string;
+  /** Current page data to send to the iframe */
+  page: Page | null;
+  /** Currently selected block ID for highlighting */
+  selectedBlockId: string | null;
+  /** Current viewport size */
+  viewport: ViewportKey;
+  /** Called when user clicks a block in the preview */
+  onBlockClicked: (blockId: string) => void;
 }
 
-export function PreviewPanel({ path = "/" }: PreviewPanelProps) {
+export function PreviewPanel({
+  path = "/",
+  page,
+  selectedBlockId,
+  viewport,
+  onBlockClicked,
+}: PreviewPanelProps) {
   const { url, isLoading } = useTunnelUrl();
+  const { setIframeRef } = useIframeBridge({
+    page,
+    selectedBlockId,
+    onBlockClicked,
+  });
 
   if (isLoading) {
     return (
@@ -45,12 +66,15 @@ export function PreviewPanel({ path = "/" }: PreviewPanelProps) {
   }
 
   const previewUrl = path !== "/" ? `${url}${path}` : url;
+  const viewportWidth = VIEWPORTS[viewport]?.width;
 
   return (
-    <div className="relative w-full h-full">
+    <div className="relative w-full h-full flex justify-center bg-muted/30">
       <iframe
+        ref={setIframeRef}
         src={previewUrl}
-        className="w-full h-full border-0"
+        style={{ width: viewportWidth ? `${viewportWidth}px` : "100%" }}
+        className="h-full border-0 bg-white shadow-md transition-[width] duration-300"
         sandbox="allow-scripts allow-same-origin allow-forms allow-popups"
         title="Site preview"
       />
diff --git a/packages/mesh-plugin-site-editor/client/components/viewport-toggle.tsx b/packages/mesh-plugin-site-editor/client/components/viewport-toggle.tsx
new file mode 100644
index 0000000000..eeae80a6b6
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/components/viewport-toggle.tsx
@@ -0,0 +1,44 @@
+/**
+ * Viewport Toggle Component
+ *
+ * Switches the preview iframe between mobile (375px), tablet (768px),
+ * and desktop (1440px) widths. Uses lucide-react icons for viewport indicators.
+ */
+
+import { Button } from "@deco/ui/components/button.tsx";
+import { Monitor, Smartphone, Tablet } from "lucide-react";
+
+export const VIEWPORTS = {
+  mobile: { width: 375, label: "Mobile", icon: Smartphone },
+  tablet: { width: 768, label: "Tablet", icon: Tablet },
+  desktop: { width: 1440, label: "Desktop", icon: Monitor },
+} as const;
+
+export type ViewportKey = keyof typeof VIEWPORTS;
+
+interface ViewportToggleProps {
+  value: ViewportKey;
+  onChange: (v: ViewportKey) => void;
+}
+
+export function ViewportToggle({ value, onChange }: ViewportToggleProps) {
+  return (
+    <div className="flex gap-1">
+      {(Object.keys(VIEWPORTS) as ViewportKey[]).map((key) => {
+        const { label, icon: Icon } = VIEWPORTS[key];
+        return (
+          <Button
+            key={key}
+            variant={value === key ? "default" : "outline"}
+            size="sm"
+            onClick={() => onChange(key)}
+            title={label}
+          >
+            <Icon size={14} />
+            <span className="sr-only">{label}</span>
+          </Button>
+        );
+      })}
+    </div>
+  );
+}
diff --git a/packages/mesh-plugin-site-editor/client/lib/use-iframe-bridge.ts b/packages/mesh-plugin-site-editor/client/lib/use-iframe-bridge.ts
new file mode 100644
index 0000000000..7b54d39270
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/lib/use-iframe-bridge.ts
@@ -0,0 +1,139 @@
+/**
+ * useIframeBridge Hook
+ *
+ * Manages the lifecycle of postMessage communication between the editor
+ * and a site iframe. Handles the deco:ready handshake, page config sending,
+ * block selection, and block click events.
+ *
+ * Uses useSyncExternalStore for the ready state (external subscription to
+ * window message events) to comply with the ban-use-effect lint rule.
+ */
+
+import { useRef, useSyncExternalStore } from "react";
+import type { RefObject } from "react";
+import { DECO_MSG_PREFIX } from "./editor-protocol";
+import type { EditorMessage, SiteMessage } from "./editor-protocol";
+import type { Page } from "./page-api";
+
+interface IframeBridgeOptions {
+  page: Page | null;
+  selectedBlockId: string | null;
+  onBlockClicked: (blockId: string) => void;
+}
+
+interface IframeBridgeResult {
+  iframeRef: RefObject<HTMLIFrameElement | null>;
+  ready: boolean;
+  send: (msg: EditorMessage) => void;
+  /** Ref callback to attach to the iframe element */
+  setIframeRef: (el: HTMLIFrameElement | null) => void;
+}
+
+/**
+ * Creates a bridge between the editor and an iframe using postMessage.
+ *
+ * The ready state is tracked as an external store subscription to avoid
+ * useEffect. The iframe's load event and window message events are managed
+ * via a subscribe/getSnapshot pattern.
+ */
+export function useIframeBridge({
+  page,
+  selectedBlockId,
+  onBlockClicked,
+}: IframeBridgeOptions): IframeBridgeResult {
+  const iframeRef = useRef<HTMLIFrameElement | null>(null);
+  const readyRef = useRef(false);
+  const pageRef = useRef(page);
+  const selectedBlockIdRef = useRef(selectedBlockId);
+  const onBlockClickedRef = useRef(onBlockClicked);
+
+  // Keep refs in sync with latest props (React Compiler handles this)
+  pageRef.current = page;
+  selectedBlockIdRef.current = selectedBlockId;
+  onBlockClickedRef.current = onBlockClicked;
+
+  const send = (msg: EditorMessage) => {
+    iframeRef.current?.contentWindow?.postMessage(msg, "*");
+  };
+
+  // Track previous page/selectedBlockId to detect changes during render
+  const prevPageRef = useRef<Page | null>(null);
+  const prevSelectedBlockIdRef = useRef<string | null>(null);
+
+  // Send updates when page or selectedBlockId change (in render, not effect)
+  if (readyRef.current) {
+    if (page && page !== prevPageRef.current) {
+      // Schedule microtask to avoid sending during render
+      queueMicrotask(() => {
+        if (readyRef.current && pageRef.current) {
+          send({ type: "deco:page-config", page: pageRef.current });
+        }
+      });
+    }
+    if (selectedBlockId && selectedBlockId !== prevSelectedBlockIdRef.current) {
+      queueMicrotask(() => {
+        if (readyRef.current && selectedBlockIdRef.current) {
+          send({
+            type: "deco:select-block",
+            blockId: selectedBlockIdRef.current,
+          });
+        }
+      });
+    }
+  }
+  prevPageRef.current = page;
+  prevSelectedBlockIdRef.current = selectedBlockId;
+
+  // Use useSyncExternalStore for the ready state
+  const ready = useSyncExternalStore(
+    (notify) => {
+      const handleMessage = (e: MessageEvent) => {
+        if (e.source !== iframeRef.current?.contentWindow) return;
+        if (!e.data?.type?.startsWith(DECO_MSG_PREFIX)) return;
+
+        const msg = e.data as SiteMessage;
+
+        if (msg.type === "deco:ready") {
+          readyRef.current = true;
+          notify();
+          // Send page config after ready handshake
+          if (pageRef.current) {
+            send({ type: "deco:page-config", page: pageRef.current });
+          }
+        }
+
+        if (msg.type === "deco:block-clicked") {
+          onBlockClickedRef.current(msg.blockId);
+        }
+      };
+
+      window.addEventListener("message", handleMessage);
+      return () => window.removeEventListener("message", handleMessage);
+    },
+    () => readyRef.current,
+    () => false, // server snapshot
+  );
+
+  const setIframeRef = (el: HTMLIFrameElement | null) => {
+    // Clean up old iframe load listener
+    const prev = iframeRef.current;
+    if (prev && prev !== el) {
+      prev.removeEventListener("load", handleIframeLoad);
+    }
+
+    iframeRef.current = el;
+
+    // Attach load listener to new iframe
+    if (el) {
+      el.addEventListener("load", handleIframeLoad);
+    }
+  };
+
+  // Using a stable function reference for the load handler
+  const handleIframeLoad = () => {
+    // Reset ready state when iframe reloads (HMR/navigation)
+    readyRef.current = false;
+  };
+
+  return { iframeRef, ready, send, setIframeRef };
+}

From bad2c47f86e8b43a8ac238edf24e816ac9ef1978 Mon Sep 17 00:00:00 2001
From: Guilherme Rodrigues <gui@deco.cx>
Date: Sat, 14 Feb 2026 10:37:57 -0300
Subject: [PATCH 12/26] feat(03-02): section list sidebar with @dnd-kit
 sortable and block picker

- SectionListSidebar with DnD reordering, selection, and delete
- BlockPicker modal with category grouping and search filter
- Added @dnd-kit/core, @dnd-kit/sortable, @dnd-kit/modifiers, @dnd-kit/utilities deps

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../client/components/block-picker.tsx        | 161 ++++++++++++++
 .../components/section-list-sidebar.tsx       | 210 ++++++++++++++++++
 packages/mesh-plugin-site-editor/package.json |   4 +
 3 files changed, 375 insertions(+)
 create mode 100644 packages/mesh-plugin-site-editor/client/components/block-picker.tsx
 create mode 100644 packages/mesh-plugin-site-editor/client/components/section-list-sidebar.tsx

diff --git a/packages/mesh-plugin-site-editor/client/components/block-picker.tsx b/packages/mesh-plugin-site-editor/client/components/block-picker.tsx
new file mode 100644
index 0000000000..79b258b8b6
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/components/block-picker.tsx
@@ -0,0 +1,161 @@
+/**
+ * Block Picker Component
+ *
+ * Modal dialog for selecting a block type from the library to add to a page.
+ * Lists available blocks grouped by category with a search filter.
+ * Uses @deco/ui Dialog and fetches blocks via block-api helpers.
+ */
+
+import { useState } from "react";
+import { SITE_BINDING } from "@decocms/bindings/site";
+import { usePluginContext } from "@decocms/mesh-sdk/plugins";
+import { useQuery } from "@tanstack/react-query";
+import {
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+} from "@deco/ui/components/dialog.tsx";
+import { Input } from "@deco/ui/components/input.tsx";
+import { cn } from "@deco/ui/lib/utils.ts";
+import { Box, Search } from "lucide-react";
+import { Loading01 } from "@untitledui/icons";
+import { queryKeys } from "../lib/query-keys";
+import { listBlocks } from "../lib/block-api";
+import type { BlockSummary } from "../lib/block-api";
+
+interface BlockPickerProps {
+  open: boolean;
+  onClose: () => void;
+  onSelect: (blockType: string, defaults: Record<string, unknown>) => void;
+}
+
+/**
+ * Group blocks by category, sorted alphabetically within each group.
+ */
+function groupByCategory(
+  blocks: BlockSummary[],
+): Record<string, BlockSummary[]> {
+  const groups: Record<string, BlockSummary[]> = {};
+  for (const block of blocks) {
+    const category = block.category || "Other";
+    if (!groups[category]) {
+      groups[category] = [];
+    }
+    groups[category].push(block);
+  }
+  for (const category of Object.keys(groups)) {
+    groups[category].sort((a, b) => a.label.localeCompare(b.label));
+  }
+  return groups;
+}
+
+export function BlockPicker({ open, onClose, onSelect }: BlockPickerProps) {
+  const { toolCaller, connectionId } = usePluginContext<typeof SITE_BINDING>();
+  const [filter, setFilter] = useState("");
+
+  const { data: blocks = [], isLoading } = useQuery({
+    queryKey: queryKeys.blocks.all(connectionId),
+    queryFn: () => listBlocks(toolCaller),
+    enabled: open,
+  });
+
+  // Filter blocks by search term
+  const filtered = filter
+    ? blocks.filter(
+        (b) =>
+          b.label.toLowerCase().includes(filter.toLowerCase()) ||
+          b.component.toLowerCase().includes(filter.toLowerCase()) ||
+          b.category.toLowerCase().includes(filter.toLowerCase()),
+      )
+    : blocks;
+
+  const grouped = groupByCategory(filtered);
+  const categoryNames = Object.keys(grouped).sort();
+
+  const handleSelect = (block: BlockSummary) => {
+    onSelect(block.id, {});
+    onClose();
+    setFilter("");
+  };
+
+  const handleOpenChange = (isOpen: boolean) => {
+    if (!isOpen) {
+      onClose();
+      setFilter("");
+    }
+  };
+
+  return (
+    <Dialog open={open} onOpenChange={handleOpenChange}>
+      <DialogContent className="sm:max-w-lg max-h-[70vh] flex flex-col">
+        <DialogHeader>
+          <DialogTitle>Add Section</DialogTitle>
+        </DialogHeader>
+
+        {/* Search filter */}
+        <div className="relative">
+          <Search
+            size={14}
+            className="absolute left-3 top-1/2 -translate-y-1/2 text-muted-foreground"
+          />
+          <Input
+            placeholder="Search blocks..."
+            value={filter}
+            onChange={(e) => setFilter(e.target.value)}
+            className="pl-9"
+          />
+        </div>
+
+        {/* Block list */}
+        <div className="flex-1 overflow-y-auto -mx-6 px-6">
+          {isLoading ? (
+            <div className="flex flex-col items-center justify-center py-8">
+              <Loading01
+                size={24}
+                className="animate-spin text-muted-foreground mb-2"
+              />
+              <p className="text-sm text-muted-foreground">Loading blocks...</p>
+            </div>
+          ) : filtered.length === 0 ? (
+            <div className="flex flex-col items-center justify-center py-8">
+              <Search size={32} className="text-muted-foreground mb-2" />
+              <p className="text-sm text-muted-foreground">
+                {filter ? "No blocks match your search" : "No blocks available"}
+              </p>
+            </div>
+          ) : (
+            categoryNames.map((category) => (
+              <div key={category} className="mb-3">
+                <div className="text-xs font-medium text-muted-foreground uppercase tracking-wider py-1.5">
+                  {category}
+                </div>
+                {grouped[category].map((block) => (
+                  <button
+                    key={block.id}
+                    type="button"
+                    onClick={() => handleSelect(block)}
+                    className={cn(
+                      "flex items-center gap-3 w-full text-left px-3 py-2 rounded transition-colors",
+                      "hover:bg-muted/50",
+                    )}
+                  >
+                    <Box size={16} className="text-muted-foreground shrink-0" />
+                    <div className="flex-1 min-w-0">
+                      <span className="text-sm font-medium block truncate">
+                        {block.label}
+                      </span>
+                      <span className="text-xs text-muted-foreground block truncate">
+                        {block.component}
+                      </span>
+                    </div>
+                  </button>
+                ))}
+              </div>
+            ))
+          )}
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}
diff --git a/packages/mesh-plugin-site-editor/client/components/section-list-sidebar.tsx b/packages/mesh-plugin-site-editor/client/components/section-list-sidebar.tsx
new file mode 100644
index 0000000000..0b78f7fc9a
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/components/section-list-sidebar.tsx
@@ -0,0 +1,210 @@
+/**
+ * Section List Sidebar Component
+ *
+ * Displays all block instances on a page in a sortable drag-and-drop list.
+ * Each row shows the block name with a drag handle, selection highlight,
+ * and delete button. Uses @dnd-kit for accessible DnD reordering.
+ */
+
+import { useState } from "react";
+import {
+  DndContext,
+  closestCenter,
+  KeyboardSensor,
+  MouseSensor,
+  TouchSensor,
+  useSensor,
+  useSensors,
+} from "@dnd-kit/core";
+import type { DragEndEvent } from "@dnd-kit/core";
+import {
+  SortableContext,
+  useSortable,
+  verticalListSortingStrategy,
+  sortableKeyboardCoordinates,
+} from "@dnd-kit/sortable";
+import { restrictToVerticalAxis } from "@dnd-kit/modifiers";
+import { CSS } from "@dnd-kit/utilities";
+import { GripVertical, Plus, Trash2 } from "lucide-react";
+import { cn } from "@deco/ui/lib/utils.ts";
+import { Button } from "@deco/ui/components/button.tsx";
+import type { BlockInstance } from "../lib/page-api";
+
+interface SectionListSidebarProps {
+  blocks: BlockInstance[];
+  selectedBlockId: string | null;
+  onSelect: (blockId: string) => void;
+  onDelete: (blockId: string) => void;
+  onReorder: (activeId: string, overId: string) => void;
+  onAddClick: () => void;
+}
+
+/**
+ * Derive a display label from a blockType ID.
+ * "sections--Hero" -> "Hero"
+ * "layout--Header" -> "Header"
+ */
+function blockLabel(blockType: string): string {
+  const parts = blockType.replace(/--/g, "/").split("/");
+  return parts[parts.length - 1] ?? blockType;
+}
+
+interface SortableSectionItemProps {
+  block: BlockInstance;
+  isSelected: boolean;
+  onSelect: () => void;
+  onDelete: () => void;
+}
+
+function SortableSectionItem({
+  block,
+  isSelected,
+  onSelect,
+  onDelete,
+}: SortableSectionItemProps) {
+  const {
+    attributes,
+    listeners,
+    setNodeRef,
+    transform,
+    transition,
+    isDragging,
+  } = useSortable({ id: block.id });
+
+  const [isHovered, setIsHovered] = useState(false);
+
+  return (
+    <div
+      ref={setNodeRef}
+      style={{
+        transform: CSS.Transform.toString(transform),
+        transition,
+      }}
+      className={cn(
+        "flex items-center gap-1.5 px-2 py-1.5 rounded text-sm transition-colors group",
+        isSelected ? "bg-accent text-accent-foreground" : "hover:bg-muted",
+        isDragging && "opacity-50 z-50",
+      )}
+      onMouseEnter={() => setIsHovered(true)}
+      onMouseLeave={() => setIsHovered(false)}
+    >
+      {/* Drag handle */}
+      <button
+        type="button"
+        className="shrink-0 cursor-grab active:cursor-grabbing text-muted-foreground hover:text-foreground p-0.5"
+        {...listeners}
+        {...attributes}
+      >
+        <GripVertical size={14} />
+      </button>
+
+      {/* Block label - clickable for selection */}
+      <button
+        type="button"
+        className="flex-1 text-left truncate"
+        onClick={onSelect}
+      >
+        {blockLabel(block.blockType)}
+      </button>
+
+      {/* Delete button - visible on hover */}
+      <button
+        type="button"
+        className={cn(
+          "shrink-0 p-0.5 text-muted-foreground hover:text-destructive transition-opacity",
+          isHovered ? "opacity-100" : "opacity-0",
+        )}
+        onClick={(e) => {
+          e.stopPropagation();
+          onDelete();
+        }}
+        title="Remove section"
+      >
+        <Trash2 size={14} />
+      </button>
+    </div>
+  );
+}
+
+export function SectionListSidebar({
+  blocks,
+  selectedBlockId,
+  onSelect,
+  onDelete,
+  onReorder,
+  onAddClick,
+}: SectionListSidebarProps) {
+  const sensors = useSensors(
+    useSensor(MouseSensor, {
+      activationConstraint: { distance: 8 },
+    }),
+    useSensor(TouchSensor),
+    useSensor(KeyboardSensor, {
+      coordinateGetter: sortableKeyboardCoordinates,
+    }),
+  );
+
+  const handleDragEnd = (event: DragEndEvent) => {
+    const { active, over } = event;
+    if (over && active.id !== over.id) {
+      onReorder(active.id as string, over.id as string);
+    }
+  };
+
+  if (blocks.length === 0) {
+    return (
+      <div className="flex flex-col items-center justify-center h-full p-4 text-center">
+        <p className="text-sm text-muted-foreground mb-3">No sections yet</p>
+        <Button variant="outline" size="sm" onClick={onAddClick}>
+          <Plus size={14} className="mr-1" />
+          Add Section
+        </Button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="flex flex-col h-full">
+      <h3 className="text-sm font-medium text-muted-foreground px-3 py-2">
+        Sections
+      </h3>
+
+      <div className="flex-1 overflow-y-auto px-1">
+        <DndContext
+          sensors={sensors}
+          collisionDetection={closestCenter}
+          modifiers={[restrictToVerticalAxis]}
+          onDragEnd={handleDragEnd}
+        >
+          <SortableContext
+            items={blocks.map((b) => b.id)}
+            strategy={verticalListSortingStrategy}
+          >
+            {blocks.map((block) => (
+              <SortableSectionItem
+                key={block.id}
+                block={block}
+                isSelected={selectedBlockId === block.id}
+                onSelect={() => onSelect(block.id)}
+                onDelete={() => onDelete(block.id)}
+              />
+            ))}
+          </SortableContext>
+        </DndContext>
+      </div>
+
+      {/* Add Section footer */}
+      <div className="border-t border-border p-2">
+        <Button
+          variant="ghost"
+          size="sm"
+          className="w-full justify-start"
+          onClick={onAddClick}
+        >
+          <Plus size={14} className="mr-1" />
+          Add Section
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/packages/mesh-plugin-site-editor/package.json b/packages/mesh-plugin-site-editor/package.json
index 84eb226a8c..724474fc30 100644
--- a/packages/mesh-plugin-site-editor/package.json
+++ b/packages/mesh-plugin-site-editor/package.json
@@ -15,6 +15,10 @@
     "@decocms/bindings": "workspace:*",
     "@decocms/mesh-sdk": "workspace:*",
     "@deco/ui": "workspace:*",
+    "@dnd-kit/core": "^6.1.0",
+    "@dnd-kit/modifiers": "^7.0.0",
+    "@dnd-kit/sortable": "^8.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
     "@rjsf/core": "^6.1.2",
     "@rjsf/utils": "^6.1.2",
     "@rjsf/validator-ajv8": "^6.1.2",

From 7662d8f6d7282635bd22fa65834b9afe9a12b26b Mon Sep 17 00:00:00 2001
From: Guilherme Rodrigues <gui@deco.cx>
Date: Sat, 14 Feb 2026 10:39:17 -0300
Subject: [PATCH 13/26] feat(03-02): wire composer with section sidebar, block
 picker, and DnD reorder

- Replace left panel placeholder with SectionListSidebar + DnD reordering via arrayMove
- Add BlockPicker modal for adding new sections from block library
- Wire onDelete, onReorder, onAddClick handlers with debounced save to git
- Invalidate query cache on successful save
- Rewrite page-editor.tsx to render PageComposer instead of metadata form

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../client/components/page-composer.tsx       | 127 +++++++---
 .../client/components/page-editor.tsx         | 228 +-----------------
 2 files changed, 98 insertions(+), 257 deletions(-)

diff --git a/packages/mesh-plugin-site-editor/client/components/page-composer.tsx b/packages/mesh-plugin-site-editor/client/components/page-composer.tsx
index 924c3431b8..3ad5b8fc0a 100644
--- a/packages/mesh-plugin-site-editor/client/components/page-composer.tsx
+++ b/packages/mesh-plugin-site-editor/client/components/page-composer.tsx
@@ -2,39 +2,49 @@
  * Page Composer Component
  *
  * Three-panel visual editor layout:
- * - Left: section list sidebar (placeholder for Plan 03-02)
+ * - Left: sortable section list sidebar with DnD reordering
  * - Center: iframe preview with viewport toggle
  * - Right: prop editor for selected block
  *
- * Fetches page data, manages selected block state, and wires postMessage
- * communication for live preview updates.
+ * Fetches page data, manages selected block state, wires postMessage
+ * communication for live preview updates, and debounce-saves to git.
  */
 
 import { useRef, useState } from "react";
+import { nanoid } from "nanoid";
 import { SITE_BINDING } from "@decocms/bindings/site";
 import { usePluginContext } from "@decocms/mesh-sdk/plugins";
-import { useQuery } from "@tanstack/react-query";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { arrayMove } from "@dnd-kit/sortable";
 import { Button } from "@deco/ui/components/button.tsx";
-import { cn } from "@deco/ui/lib/utils.ts";
 import { ArrowLeft, Save01, Loading01, AlertCircle } from "@untitledui/icons";
 import { toast } from "sonner";
 import { queryKeys } from "../lib/query-keys";
 import { siteEditorRouter } from "../lib/router";
-import { getPage, updatePage, type Page } from "../lib/page-api";
+import {
+  getPage,
+  updatePage,
+  type BlockInstance,
+  type Page,
+} from "../lib/page-api";
 import { getBlock } from "../lib/block-api";
 import { useEditorMessages } from "../lib/use-editor-messages";
 import { PreviewPanel } from "./preview-panel";
 import { ViewportToggle, type ViewportKey } from "./viewport-toggle";
 import { PropEditor } from "./prop-editor";
+import { SectionListSidebar } from "./section-list-sidebar";
+import { BlockPicker } from "./block-picker";
 
 export default function PageComposer() {
   const { toolCaller, connectionId } = usePluginContext<typeof SITE_BINDING>();
+  const queryClient = useQueryClient();
   const navigate = siteEditorRouter.useNavigate();
   const { pageId } = siteEditorRouter.useParams({ from: "/pages/$pageId" });
 
   const [selectedBlockId, setSelectedBlockId] = useState<string | null>(null);
   const [viewport, setViewport] = useState<ViewportKey>("desktop");
   const [localPage, setLocalPage] = useState<Page | null>(null);
+  const [showBlockPicker, setShowBlockPicker] = useState(false);
   const saveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const iframeRef = useRef<HTMLIFrameElement>(null);
   const { send } = useEditorMessages(iframeRef);
@@ -79,6 +89,9 @@ export default function PageComposer() {
         await updatePage(toolCaller, pageId, {
           blocks: updatedPage.blocks,
         });
+        queryClient.invalidateQueries({
+          queryKey: queryKeys.pages.detail(connectionId, pageId),
+        });
       } catch (err) {
         toast.error(
           `Failed to save: ${err instanceof Error ? err.message : "Unknown error"}`,
@@ -87,6 +100,14 @@ export default function PageComposer() {
     }, 2000);
   };
 
+  // Helper to update local page and trigger save
+  const applyPageUpdate = (updater: (prev: Page) => Page) => {
+    if (!localPage) return;
+    const updatedPage = updater(localPage);
+    setLocalPage(updatedPage);
+    debouncedSave(updatedPage);
+  };
+
   // Handle prop changes from PropEditor
   const handlePropChange = (newProps: Record<string, unknown>) => {
     if (!localPage || !selectedBlockId) return;
@@ -113,7 +134,51 @@ export default function PageComposer() {
     debouncedSave(updatedPage);
   };
 
-  // Manual save
+  // Handle block deletion
+  const handleDeleteBlock = (blockId: string) => {
+    applyPageUpdate((prev) => ({
+      ...prev,
+      blocks: prev.blocks.filter((b) => b.id !== blockId),
+    }));
+    if (selectedBlockId === blockId) {
+      setSelectedBlockId(null);
+    }
+  };
+
+  // Handle block reordering via DnD
+  const handleReorder = (activeId: string, overId: string) => {
+    if (!localPage) return;
+    const oldIndex = localPage.blocks.findIndex((b) => b.id === activeId);
+    const newIndex = localPage.blocks.findIndex((b) => b.id === overId);
+    if (oldIndex === -1 || newIndex === -1) return;
+
+    applyPageUpdate((prev) => ({
+      ...prev,
+      blocks: arrayMove(prev.blocks, oldIndex, newIndex),
+    }));
+  };
+
+  // Handle adding a new block from the picker
+  const handleAddBlock = (
+    blockType: string,
+    defaults: Record<string, unknown>,
+  ) => {
+    const newBlock: BlockInstance = {
+      id: nanoid(8),
+      blockType,
+      props: defaults,
+    };
+
+    applyPageUpdate((prev) => ({
+      ...prev,
+      blocks: [...prev.blocks, newBlock],
+    }));
+
+    setSelectedBlockId(newBlock.id);
+    setShowBlockPicker(false);
+  };
+
+  // Manual save (flush debounce)
   const handleSave = async () => {
     if (!localPage) return;
     if (saveTimerRef.current) {
@@ -127,6 +192,9 @@ export default function PageComposer() {
         blocks: localPage.blocks,
       });
       toast.success("Page saved");
+      queryClient.invalidateQueries({
+        queryKey: queryKeys.pages.detail(connectionId, pageId),
+      });
     } catch (err) {
       toast.error(
         `Failed to save: ${err instanceof Error ? err.message : "Unknown error"}`,
@@ -201,34 +269,16 @@ export default function PageComposer() {
 
       {/* Three-panel layout */}
       <div className="flex flex-1 overflow-hidden">
-        {/* Left panel: section list (placeholder for Plan 03-02) */}
-        <div className="w-[260px] border-r border-border overflow-y-auto p-4">
-          <h3 className="text-sm font-medium text-muted-foreground mb-3">
-            Sections
-          </h3>
-          {localPage.blocks.length === 0 ? (
-            <p className="text-xs text-muted-foreground">
-              No sections yet. Add sections in Plan 03-02.
-            </p>
-          ) : (
-            <div className="space-y-1">
-              {localPage.blocks.map((block) => (
-                <button
-                  key={block.id}
-                  type="button"
-                  onClick={() => setSelectedBlockId(block.id)}
-                  className={cn(
-                    "w-full text-left px-3 py-2 rounded text-sm transition-colors",
-                    selectedBlockId === block.id
-                      ? "bg-accent text-accent-foreground"
-                      : "hover:bg-muted",
-                  )}
-                >
-                  {block.blockType.replace("sections--", "")}
-                </button>
-              ))}
-            </div>
-          )}
+        {/* Left panel: sortable section list */}
+        <div className="w-[260px] border-r border-border overflow-y-auto">
+          <SectionListSidebar
+            blocks={localPage.blocks}
+            selectedBlockId={selectedBlockId}
+            onSelect={setSelectedBlockId}
+            onDelete={handleDeleteBlock}
+            onReorder={handleReorder}
+            onAddClick={() => setShowBlockPicker(true)}
+          />
         </div>
 
         {/* Center panel: preview */}
@@ -271,6 +321,13 @@ export default function PageComposer() {
           )}
         </div>
       </div>
+
+      {/* Block picker modal */}
+      <BlockPicker
+        open={showBlockPicker}
+        onClose={() => setShowBlockPicker(false)}
+        onSelect={handleAddBlock}
+      />
     </div>
   );
 }
diff --git a/packages/mesh-plugin-site-editor/client/components/page-editor.tsx b/packages/mesh-plugin-site-editor/client/components/page-editor.tsx
index 1f70cb79fd..df5a0fee8b 100644
--- a/packages/mesh-plugin-site-editor/client/components/page-editor.tsx
+++ b/packages/mesh-plugin-site-editor/client/components/page-editor.tsx
@@ -1,232 +1,16 @@
 /**
  * Page Editor Component
  *
- * Form for editing page metadata (title, path).
- * Blocks editing is deferred to Phase 3.
- * Uses SITE_BINDING tools (READ_FILE, PUT_FILE) via page-api helpers.
+ * Route component for /pages/$pageId.
+ * Renders the visual PageComposer for block editing with live preview.
  */
 
-import { useRef, useState } from "react";
-import { SITE_BINDING } from "@decocms/bindings/site";
-import { usePluginContext } from "@decocms/mesh-sdk/plugins";
-import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
-import { Button } from "@deco/ui/components/button.tsx";
-import { Input } from "@deco/ui/components/input.tsx";
-import { Label } from "@deco/ui/components/label.tsx";
-import { ArrowLeft, Save01, Loading01, AlertCircle } from "@untitledui/icons";
-import { toast } from "sonner";
-import { queryKeys } from "../lib/query-keys";
 import { siteEditorRouter } from "../lib/router";
-import { getPage, updatePage } from "../lib/page-api";
-
-function formatTimestamp(dateStr: string): string {
-  if (!dateStr) return "-";
-  try {
-    return new Date(dateStr).toLocaleString(undefined, {
-      year: "numeric",
-      month: "short",
-      day: "numeric",
-      hour: "2-digit",
-      minute: "2-digit",
-      second: "2-digit",
-    });
-  } catch {
-    return dateStr;
-  }
-}
+import PageComposer from "./page-composer";
 
 export default function PageEditor() {
-  const { toolCaller, connectionId } = usePluginContext<typeof SITE_BINDING>();
-  const queryClient = useQueryClient();
-  const navigate = siteEditorRouter.useNavigate();
-  const { pageId } = siteEditorRouter.useParams({ from: "/pages/$pageId" });
-
-  const [title, setTitle] = useState("");
-  const [path, setPath] = useState("");
-  const [isDirty, setIsDirty] = useState(false);
-  const lastSyncedPageId = useRef<string | null>(null);
-
-  // Fetch page
-  const {
-    data: page,
-    isLoading,
-    error,
-  } = useQuery({
-    queryKey: queryKeys.pages.detail(connectionId, pageId),
-    queryFn: () => getPage(toolCaller, pageId),
-  });
-
-  // Sync form state when page data loads (replaces useEffect)
-  if (page && lastSyncedPageId.current !== page.metadata.updatedAt) {
-    lastSyncedPageId.current = page.metadata.updatedAt;
-    setTitle(page.title);
-    setPath(page.path);
-    setIsDirty(false);
-  }
-
-  // Save mutation
-  const saveMutation = useMutation({
-    mutationFn: () => updatePage(toolCaller, pageId, { title, path }),
-    onSuccess: (updatedPage) => {
-      toast.success("Page saved");
-      setIsDirty(false);
-      queryClient.setQueryData(
-        queryKeys.pages.detail(connectionId, pageId),
-        updatedPage,
-      );
-      queryClient.invalidateQueries({
-        queryKey: queryKeys.pages.all(connectionId),
-      });
-    },
-    onError: (err) => {
-      toast.error(
-        `Failed to save: ${err instanceof Error ? err.message : "Unknown error"}`,
-      );
-    },
-  });
-
-  const handleTitleChange = (value: string) => {
-    setTitle(value);
-    setIsDirty(true);
-  };
-
-  const handlePathChange = (value: string) => {
-    setPath(value);
-    setIsDirty(true);
-  };
-
-  const handleSave = () => {
-    saveMutation.mutate();
-  };
-
-  if (isLoading) {
-    return (
-      <div className="flex flex-col items-center justify-center h-full p-8">
-        <Loading01
-          size={32}
-          className="animate-spin text-muted-foreground mb-4"
-        />
-        <p className="text-sm text-muted-foreground">Loading page...</p>
-      </div>
-    );
-  }
-
-  if (error) {
-    return (
-      <div className="flex flex-col items-center justify-center h-full p-8">
-        <AlertCircle size={48} className="text-destructive mb-4" />
-        <h3 className="text-lg font-medium mb-2">Error loading page</h3>
-        <p className="text-muted-foreground text-center">
-          {error instanceof Error ? error.message : "Unknown error"}
-        </p>
-      </div>
-    );
-  }
-
-  if (!page) {
-    return (
-      <div className="flex flex-col items-center justify-center h-full p-8">
-        <AlertCircle size={48} className="text-muted-foreground mb-4" />
-        <h3 className="text-lg font-medium mb-2">Page not found</h3>
-        <p className="text-muted-foreground text-center mb-4">
-          The page "{pageId}" could not be found.
-        </p>
-        <Button variant="outline" onClick={() => navigate({ to: "/" })}>
-          <ArrowLeft size={14} className="mr-1" />
-          Back to Pages
-        </Button>
-      </div>
-    );
-  }
-
-  return (
-    <div className="flex flex-col h-full">
-      {/* Header with breadcrumb */}
-      <div className="flex items-center justify-between px-4 py-3 border-b border-border bg-background">
-        <div className="flex items-center gap-2 text-sm">
-          <button
-            type="button"
-            onClick={() => navigate({ to: "/" })}
-            className="text-muted-foreground hover:text-foreground transition-colors"
-          >
-            Pages
-          </button>
-          <span className="text-muted-foreground">/</span>
-          <span className="font-medium">{page.title}</span>
-        </div>
-        <Button
-          size="sm"
-          onClick={handleSave}
-          disabled={!isDirty || saveMutation.isPending}
-        >
-          {saveMutation.isPending ? (
-            <Loading01 size={14} className="mr-1 animate-spin" />
-          ) : (
-            <Save01 size={14} className="mr-1" />
-          )}
-          Save
-        </Button>
-      </div>
-
-      {/* Form content */}
-      <div className="flex-1 overflow-y-auto p-6">
-        <div className="max-w-2xl space-y-6">
-          {/* Title field */}
-          <div className="grid gap-2">
-            <Label htmlFor="edit-title">Title</Label>
-            <Input
-              id="edit-title"
-              value={title}
-              onChange={(e) => handleTitleChange(e.target.value)}
-              onKeyDown={(e) => {
-                if (e.key === "Enter" && isDirty) handleSave();
-              }}
-            />
-          </div>
-
-          {/* Path field */}
-          <div className="grid gap-2">
-            <Label htmlFor="edit-path">Path</Label>
-            <Input
-              id="edit-path"
-              value={path}
-              onChange={(e) => handlePathChange(e.target.value)}
-              onKeyDown={(e) => {
-                if (e.key === "Enter" && isDirty) handleSave();
-              }}
-            />
-          </div>
+  // Validate route params are available
+  siteEditorRouter.useParams({ from: "/pages/$pageId" });
 
-          {/* Metadata (read-only) */}
-          <div className="border border-border rounded-lg p-4 space-y-3">
-            <h3 className="text-sm font-medium text-muted-foreground">
-              Metadata
-            </h3>
-            <div className="grid grid-cols-2 gap-3 text-sm">
-              <div>
-                <span className="text-muted-foreground">ID</span>
-                <p className="font-mono text-xs mt-0.5">{page.id}</p>
-              </div>
-              <div>
-                <span className="text-muted-foreground">Blocks</span>
-                <p className="mt-0.5">{page.blocks.length} blocks</p>
-              </div>
-              <div>
-                <span className="text-muted-foreground">Created</span>
-                <p className="mt-0.5">
-                  {formatTimestamp(page.metadata.createdAt)}
-                </p>
-              </div>
-              <div>
-                <span className="text-muted-foreground">Last Updated</span>
-                <p className="mt-0.5">
-                  {formatTimestamp(page.metadata.updatedAt)}
-                </p>
-              </div>
-            </div>
-          </div>
-        </div>
-      </div>
-    </div>
-  );
+  return <PageComposer />;
 }

From 2e08aa51eb95114d500dafc4ddcad8b39788656c Mon Sep 17 00:00:00 2001
From: Guilherme Rodrigues <gui@deco.cx>
Date: Sat, 14 Feb 2026 10:43:23 -0300
Subject: [PATCH 14/26] feat(03-03): snapshot-based undo/redo hook with
 useReducer

- Generic useUndoRedo<T> hook with push/undo/redo/reset/clearFuture
- Atomic state transitions via useReducer (past/present/future)
- 100-entry cap on past stack to prevent unbounded memory growth
- clearFuture action for clearing redo stack after save

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../client/lib/use-undo-redo.ts               | 113 ++++++++++++++++++
 1 file changed, 113 insertions(+)
 create mode 100644 packages/mesh-plugin-site-editor/client/lib/use-undo-redo.ts

diff --git a/packages/mesh-plugin-site-editor/client/lib/use-undo-redo.ts b/packages/mesh-plugin-site-editor/client/lib/use-undo-redo.ts
new file mode 100644
index 0000000000..afecd7cd1d
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/lib/use-undo-redo.ts
@@ -0,0 +1,113 @@
+/**
+ * useUndoRedo Hook
+ *
+ * Generic snapshot-based undo/redo state manager using useReducer
+ * for atomic transitions between past/present/future stacks.
+ *
+ * - push(next): Records current as past, sets next as present, clears future
+ * - undo(): Moves present to future, restores last past entry
+ * - redo(): Moves present to past, restores first future entry
+ * - reset(value): Replaces all state with a new initial value
+ * - clearFuture(): Clears redo stack (used after save to prevent divergence)
+ *
+ * Past stack is capped at 100 entries to prevent unbounded memory growth.
+ */
+
+import { useReducer } from "react";
+
+const MAX_PAST_SIZE = 100;
+
+type Action<T> =
+  | { type: "PUSH"; value: T }
+  | { type: "UNDO" }
+  | { type: "REDO" }
+  | { type: "RESET"; value: T }
+  | { type: "CLEAR_FUTURE" };
+
+interface State<T> {
+  past: T[];
+  present: T;
+  future: T[];
+}
+
+function reducer<T>(state: State<T>, action: Action<T>): State<T> {
+  switch (action.type) {
+    case "PUSH": {
+      const newPast = [...state.past, state.present];
+      // Cap past stack at MAX_PAST_SIZE, dropping oldest entries
+      if (newPast.length > MAX_PAST_SIZE) {
+        newPast.splice(0, newPast.length - MAX_PAST_SIZE);
+      }
+      return {
+        past: newPast,
+        present: action.value,
+        future: [],
+      };
+    }
+    case "UNDO": {
+      if (state.past.length === 0) return state;
+      return {
+        past: state.past.slice(0, -1),
+        present: state.past[state.past.length - 1],
+        future: [state.present, ...state.future],
+      };
+    }
+    case "REDO": {
+      if (state.future.length === 0) return state;
+      return {
+        past: [...state.past, state.present],
+        present: state.future[0],
+        future: state.future.slice(1),
+      };
+    }
+    case "RESET":
+      return { past: [], present: action.value, future: [] };
+    case "CLEAR_FUTURE":
+      return state.future.length === 0 ? state : { ...state, future: [] };
+  }
+}
+
+export interface UseUndoRedoResult<T> {
+  /** Current value */
+  value: T;
+  /** Push a new state snapshot (clears redo stack) */
+  push: (next: T) => void;
+  /** Revert to previous state */
+  undo: () => void;
+  /** Re-apply a previously undone state */
+  redo: () => void;
+  /** Whether undo is available */
+  canUndo: boolean;
+  /** Whether redo is available */
+  canRedo: boolean;
+  /** Reset to a new initial value (clears both stacks) */
+  reset: (newInitial: T) => void;
+  /** Clear redo stack only (used after save to prevent divergence) */
+  clearFuture: () => void;
+}
+
+export function useUndoRedo<T>(initial: T): UseUndoRedoResult<T> {
+  const [state, dispatch] = useReducer(reducer<T>, {
+    past: [],
+    present: initial,
+    future: [],
+  });
+
+  const push = (next: T) => dispatch({ type: "PUSH", value: next });
+  const undo = () => dispatch({ type: "UNDO" });
+  const redo = () => dispatch({ type: "REDO" });
+  const reset = (newInitial: T) =>
+    dispatch({ type: "RESET", value: newInitial });
+  const clearFuture = () => dispatch({ type: "CLEAR_FUTURE" });
+
+  return {
+    value: state.present as T,
+    push,
+    undo,
+    redo,
+    canUndo: state.past.length > 0,
+    canRedo: state.future.length > 0,
+    reset,
+    clearFuture,
+  };
+}

From 32803030b01e4a73a31b97906c73fa646fce4808 Mon Sep 17 00:00:00 2001
From: Guilherme Rodrigues <gui@deco.cx>
Date: Sat, 14 Feb 2026 10:45:28 -0300
Subject: [PATCH 15/26] feat(03-03): integrate undo/redo into page composer
 with keyboard shortcuts

- Replace local page state with useUndoRedo<BlockInstance[]> hook
- All edit operations (prop change, reorder, add, delete) push snapshots
- Keyboard shortcuts: Cmd+Z undo, Cmd+Shift+Z/Cmd+Y redo
- Undo/redo toolbar buttons with disabled state when stack empty
- Preview iframe updates on undo/redo via deco:page-config postMessage
- Redo stack cleared on save (debounced and manual) to prevent divergence

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../client/components/page-composer.tsx       | 166 +++++++++++++-----
 1 file changed, 120 insertions(+), 46 deletions(-)

diff --git a/packages/mesh-plugin-site-editor/client/components/page-composer.tsx b/packages/mesh-plugin-site-editor/client/components/page-composer.tsx
index 3ad5b8fc0a..7bc7407d7f 100644
--- a/packages/mesh-plugin-site-editor/client/components/page-composer.tsx
+++ b/packages/mesh-plugin-site-editor/client/components/page-composer.tsx
@@ -10,25 +10,28 @@
  * communication for live preview updates, and debounce-saves to git.
  */
 
-import { useRef, useState } from "react";
+import { useRef, useState, useSyncExternalStore } from "react";
 import { nanoid } from "nanoid";
 import { SITE_BINDING } from "@decocms/bindings/site";
 import { usePluginContext } from "@decocms/mesh-sdk/plugins";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
 import { arrayMove } from "@dnd-kit/sortable";
 import { Button } from "@deco/ui/components/button.tsx";
-import { ArrowLeft, Save01, Loading01, AlertCircle } from "@untitledui/icons";
+import {
+  ArrowLeft,
+  Save01,
+  Loading01,
+  AlertCircle,
+  ReverseLeft,
+  ReverseRight,
+} from "@untitledui/icons";
 import { toast } from "sonner";
 import { queryKeys } from "../lib/query-keys";
 import { siteEditorRouter } from "../lib/router";
-import {
-  getPage,
-  updatePage,
-  type BlockInstance,
-  type Page,
-} from "../lib/page-api";
+import { getPage, updatePage, type BlockInstance } from "../lib/page-api";
 import { getBlock } from "../lib/block-api";
 import { useEditorMessages } from "../lib/use-editor-messages";
+import { useUndoRedo } from "../lib/use-undo-redo";
 import { PreviewPanel } from "./preview-panel";
 import { ViewportToggle, type ViewportKey } from "./viewport-toggle";
 import { PropEditor } from "./prop-editor";
@@ -43,7 +46,6 @@ export default function PageComposer() {
 
   const [selectedBlockId, setSelectedBlockId] = useState<string | null>(null);
   const [viewport, setViewport] = useState<ViewportKey>("desktop");
-  const [localPage, setLocalPage] = useState<Page | null>(null);
   const [showBlockPicker, setShowBlockPicker] = useState(false);
   const saveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const iframeRef = useRef<HTMLIFrameElement>(null);
@@ -59,15 +61,30 @@ export default function PageComposer() {
     queryFn: () => getPage(toolCaller, pageId),
   });
 
-  // Sync local page copy when server data loads
+  // Undo/redo state for blocks
+  const {
+    value: blocks,
+    push: pushBlocks,
+    undo,
+    redo,
+    canUndo,
+    canRedo,
+    reset: resetBlocks,
+    clearFuture,
+  } = useUndoRedo<BlockInstance[]>(page?.blocks ?? []);
+
+  // Sync blocks when server data loads
   const lastSyncedRef = useRef<string | null>(null);
   if (page && lastSyncedRef.current !== page.metadata.updatedAt) {
     lastSyncedRef.current = page.metadata.updatedAt;
-    setLocalPage(page);
+    resetBlocks(page.blocks);
   }
 
+  // Build the local page object from query data + undo/redo blocks
+  const localPage = page ? { ...page, blocks } : null;
+
   // Find selected block
-  const selectedBlock = localPage?.blocks.find((b) => b.id === selectedBlockId);
+  const selectedBlock = blocks.find((b) => b.id === selectedBlockId);
 
   // Fetch block definition (schema) for the selected block
   const { data: blockDef } = useQuery({
@@ -79,16 +96,69 @@ export default function PageComposer() {
     enabled: !!selectedBlock,
   });
 
+  // Send page-config to iframe whenever blocks change (undo/redo or direct edit)
+  const prevBlocksRef = useRef<BlockInstance[]>(blocks);
+  if (localPage && blocks !== prevBlocksRef.current) {
+    prevBlocksRef.current = blocks;
+    queueMicrotask(() => {
+      if (localPage) {
+        send({ type: "deco:page-config", page: localPage });
+      }
+    });
+  }
+
+  // Keyboard shortcuts for undo/redo via useSyncExternalStore
+  const undoRef = useRef(undo);
+  const redoRef = useRef(redo);
+  undoRef.current = undo;
+  redoRef.current = redo;
+
+  useSyncExternalStore(
+    (notify) => {
+      const handler = (e: KeyboardEvent) => {
+        const mod = e.metaKey || e.ctrlKey;
+        if (!mod) return;
+
+        // Redo: Cmd+Shift+Z or Cmd+Y
+        if ((e.key === "z" || e.key === "Z") && e.shiftKey && mod) {
+          e.preventDefault();
+          redoRef.current();
+          notify();
+          return;
+        }
+        if ((e.key === "y" || e.key === "Y") && mod && !e.shiftKey) {
+          e.preventDefault();
+          redoRef.current();
+          notify();
+          return;
+        }
+        // Undo: Cmd+Z (no shift)
+        if ((e.key === "z" || e.key === "Z") && mod && !e.shiftKey) {
+          e.preventDefault();
+          undoRef.current();
+          notify();
+          return;
+        }
+      };
+
+      window.addEventListener("keydown", handler);
+      return () => window.removeEventListener("keydown", handler);
+    },
+    () => null,
+    () => null,
+  );
+
   // Debounced save to git
-  const debouncedSave = (updatedPage: Page) => {
+  const debouncedSave = (updatedBlocks: BlockInstance[]) => {
     if (saveTimerRef.current) {
       clearTimeout(saveTimerRef.current);
     }
     saveTimerRef.current = setTimeout(async () => {
       try {
         await updatePage(toolCaller, pageId, {
-          blocks: updatedPage.blocks,
+          blocks: updatedBlocks,
         });
+        clearFuture();
         queryClient.invalidateQueries({
           queryKey: queryKeys.pages.detail(connectionId, pageId),
         });
@@ -100,28 +170,15 @@ export default function PageComposer() {
     }, 2000);
   };
 
-  // Helper to update local page and trigger save
-  const applyPageUpdate = (updater: (prev: Page) => Page) => {
-    if (!localPage) return;
-    const updatedPage = updater(localPage);
-    setLocalPage(updatedPage);
-    debouncedSave(updatedPage);
-  };
-
   // Handle prop changes from PropEditor
   const handlePropChange = (newProps: Record<string, unknown>) => {
-    if (!localPage || !selectedBlockId) return;
+    if (!selectedBlockId) return;
 
-    const updatedBlocks = localPage.blocks.map((block) =>
+    const updatedBlocks = blocks.map((block) =>
       block.id === selectedBlockId ? { ...block, props: newProps } : block,
     );
 
-    const updatedPage: Page = {
-      ...localPage,
-      blocks: updatedBlocks,
-    };
-
-    setLocalPage(updatedPage);
+    pushBlocks(updatedBlocks);
 
     // Immediately send to iframe for live preview
     send({
@@ -131,15 +188,14 @@ export default function PageComposer() {
     });
 
     // Debounce save to git
-    debouncedSave(updatedPage);
+    debouncedSave(updatedBlocks);
   };
 
   // Handle block deletion
   const handleDeleteBlock = (blockId: string) => {
-    applyPageUpdate((prev) => ({
-      ...prev,
-      blocks: prev.blocks.filter((b) => b.id !== blockId),
-    }));
+    const updatedBlocks = blocks.filter((b) => b.id !== blockId);
+    pushBlocks(updatedBlocks);
+    debouncedSave(updatedBlocks);
     if (selectedBlockId === blockId) {
       setSelectedBlockId(null);
     }
@@ -147,15 +203,13 @@ export default function PageComposer() {
 
   // Handle block reordering via DnD
   const handleReorder = (activeId: string, overId: string) => {
-    if (!localPage) return;
-    const oldIndex = localPage.blocks.findIndex((b) => b.id === activeId);
-    const newIndex = localPage.blocks.findIndex((b) => b.id === overId);
+    const oldIndex = blocks.findIndex((b) => b.id === activeId);
+    const newIndex = blocks.findIndex((b) => b.id === overId);
     if (oldIndex === -1 || newIndex === -1) return;
 
-    applyPageUpdate((prev) => ({
-      ...prev,
-      blocks: arrayMove(prev.blocks, oldIndex, newIndex),
-    }));
+    const reorderedBlocks = arrayMove(blocks, oldIndex, newIndex);
+    pushBlocks(reorderedBlocks);
+    debouncedSave(reorderedBlocks);
   };
 
   // Handle adding a new block from the picker
@@ -169,10 +223,9 @@ export default function PageComposer() {
       props: defaults,
     };
 
-    applyPageUpdate((prev) => ({
-      ...prev,
-      blocks: [...prev.blocks, newBlock],
-    }));
+    const updatedBlocks = [...blocks, newBlock];
+    pushBlocks(updatedBlocks);
+    debouncedSave(updatedBlocks);
 
     setSelectedBlockId(newBlock.id);
     setShowBlockPicker(false);
@@ -191,6 +244,7 @@ export default function PageComposer() {
         path: localPage.path,
         blocks: localPage.blocks,
       });
+      clearFuture();
       toast.success("Page saved");
       queryClient.invalidateQueries({
         queryKey: queryKeys.pages.detail(connectionId, pageId),
@@ -259,6 +313,26 @@ export default function PageComposer() {
         </div>
 
         <div className="flex items-center gap-3">
+          <div className="flex items-center gap-1">
+            <Button
+              variant="ghost"
+              size="icon"
+              disabled={!canUndo}
+              onClick={undo}
+              title="Undo (Cmd+Z)"
+            >
+              <ReverseLeft size={16} />
+            </Button>
+            <Button
+              variant="ghost"
+              size="icon"
+              disabled={!canRedo}
+              onClick={redo}
+              title="Redo (Cmd+Shift+Z)"
+            >
+              <ReverseRight size={16} />
+            </Button>
+          </div>
           <ViewportToggle value={viewport} onChange={setViewport} />
           <Button size="sm" onClick={handleSave}>
             <Save01 size={14} className="mr-1" />

From 4c8b010cb8805f044b84ee3de0a184c72883141a Mon Sep 17 00:00:00 2001
From: Guilherme Rodrigues <gui@deco.cx>
Date: Sat, 14 Feb 2026 10:59:33 -0300
Subject: [PATCH 16/26] feat(04-01): add LoaderDefinition types and
 discoverLoaders scanner

- Add LoaderInfo, LoaderDefinition, LoaderSummary, LoaderRef types to scanner types
- Add discoverLoaders() function that scans .ts files for default-exported functions
- Extract both input Props type and unwrapped Promise return type
- Skip functions with JSX return types (those are components)
- Support zero-parameter loaders (propsTypeName = null)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../server/scanner/discover.ts                | 243 +++++++++++++++++-
 .../server/scanner/types.ts                   |  70 +++++
 2 files changed, 312 insertions(+), 1 deletion(-)

diff --git a/packages/mesh-plugin-site-editor/server/scanner/discover.ts b/packages/mesh-plugin-site-editor/server/scanner/discover.ts
index dfc7a8d213..3b85bf91d5 100644
--- a/packages/mesh-plugin-site-editor/server/scanner/discover.ts
+++ b/packages/mesh-plugin-site-editor/server/scanner/discover.ts
@@ -17,7 +17,7 @@ import {
   type ArrowFunction,
   type FunctionExpression,
 } from "ts-morph";
-import type { ComponentInfo } from "./types.js";
+import type { ComponentInfo, LoaderInfo } from "./types.js";
 
 /**
  * JSX return type indicators. If a function's return type text contains any of
@@ -303,3 +303,244 @@ function extractJsDocFromParent(
 
   return "";
 }
+
+// ---------------------------------------------------------------------------
+// Loader discovery
+// ---------------------------------------------------------------------------
+
+/**
+ * Unwrap Promise<T> from a return type text, returning the inner type text.
+ * Also strips trailing `| null` and `| undefined` for cleaner type name lookup.
+ */
+function unwrapPromise(typeText: string): string {
+  let inner = typeText;
+
+  // Unwrap Promise<...>
+  const promiseMatch = inner.match(/^Promise<(.+)>$/s);
+  if (promiseMatch) {
+    inner = promiseMatch[1];
+  }
+
+  return inner;
+}
+
+/**
+ * Strip nullable wrappers (| null | undefined) to get the core type name.
+ */
+function stripNullable(typeText: string): string {
+  return typeText
+    .split("|")
+    .map((s) => s.trim())
+    .filter((s) => s !== "null" && s !== "undefined")
+    .join(" | ");
+}
+
+/**
+ * Discover exported loader functions in the project's .ts source files.
+ *
+ * Loaders differ from components:
+ * - Only .ts files (not .tsx)
+ * - Default-exported async functions that do NOT return JSX
+ * - Extract both input Props type and return type
+ * - Zero-parameter loaders are valid (propsTypeName = null)
+ *
+ * @param project - ts-morph Project populated with source files
+ * @returns Array of discovered loaders with their metadata
+ */
+export function discoverLoaders(project: Project): LoaderInfo[] {
+  const loaders: LoaderInfo[] = [];
+
+  for (const sourceFile of project.getSourceFiles()) {
+    const filePath = sourceFile.getFilePath();
+
+    // Only scan .ts files, skip .tsx (those are components)
+    if (!filePath.endsWith(".ts") || filePath.endsWith(".d.ts")) continue;
+
+    const defaultExportSymbol = sourceFile.getDefaultExportSymbol();
+    if (!defaultExportSymbol) continue;
+
+    const declarations = defaultExportSymbol.getDeclarations();
+
+    for (const decl of declarations) {
+      const loaderInfo = extractLoaderFromDecl(decl, sourceFile, filePath);
+      if (loaderInfo) {
+        loaders.push(loaderInfo);
+        break; // One loader per file
+      }
+    }
+  }
+
+  return loaders;
+}
+
+/**
+ * Try to extract loader info from a declaration node.
+ */
+function extractLoaderFromDecl(
+  // deno-lint-ignore no-explicit-any
+  decl: any,
+  sourceFile: SourceFile,
+  filePath: string,
+): LoaderInfo | null {
+  // Direct function declaration: export default async function loader(props: Props) { ... }
+  if (decl.isKind(SyntaxKind.FunctionDeclaration)) {
+    return extractLoaderFromFunction(
+      decl as FunctionDeclaration,
+      sourceFile,
+      filePath,
+    );
+  }
+
+  // Variable declaration: const loader = async (props: Props) => { ... }; export default loader;
+  if (decl.isKind(SyntaxKind.VariableDeclaration)) {
+    const varDecl = decl as VariableDeclaration;
+    const initializer = varDecl.getInitializer();
+
+    if (
+      initializer?.isKind(SyntaxKind.ArrowFunction) ||
+      initializer?.isKind(SyntaxKind.FunctionExpression)
+    ) {
+      const fn = initializer as ArrowFunction | FunctionExpression;
+      return extractLoaderFromCallable(
+        fn,
+        varDecl.getName(),
+        sourceFile,
+        filePath,
+      );
+    }
+  }
+
+  // Export assignment: export default expression
+  if (decl.isKind(SyntaxKind.ExportAssignment)) {
+    const expr = decl.getExpression();
+    if (!expr) return null;
+
+    const symbol = expr.getSymbol();
+    if (!symbol) return null;
+
+    for (const symDecl of symbol.getDeclarations()) {
+      if (symDecl.isKind(SyntaxKind.FunctionDeclaration)) {
+        return extractLoaderFromFunction(
+          symDecl as FunctionDeclaration,
+          sourceFile,
+          filePath,
+        );
+      }
+      if (symDecl.isKind(SyntaxKind.VariableDeclaration)) {
+        const init = (symDecl as VariableDeclaration).getInitializer();
+        if (
+          init?.isKind(SyntaxKind.ArrowFunction) ||
+          init?.isKind(SyntaxKind.FunctionExpression)
+        ) {
+          return extractLoaderFromCallable(
+            init as ArrowFunction | FunctionExpression,
+            (symDecl as VariableDeclaration).getName(),
+            sourceFile,
+            filePath,
+          );
+        }
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Extract loader info from a function declaration.
+ * Unlike components, loaders can have zero parameters.
+ */
+function extractLoaderFromFunction(
+  fn: FunctionDeclaration,
+  sourceFile: SourceFile,
+  filePath: string,
+): LoaderInfo | null {
+  const returnTypeText = fn.getReturnType().getText();
+
+  // Skip if the return type looks like JSX (that's a component, not a loader)
+  if (looksLikeJSX(returnTypeText)) return null;
+
+  // Extract props type from first parameter (may be absent)
+  let propsTypeName: string | null = null;
+  const params = fn.getParameters();
+  if (params.length > 0) {
+    const propsType = params[0].getType();
+    propsTypeName =
+      propsType.getAliasSymbol()?.getName() ??
+      propsType.getSymbol()?.getName() ??
+      null;
+  }
+
+  // Extract return type name, unwrapping Promise<T>
+  const returnTypeName = resolveReturnTypeName(returnTypeText);
+
+  return {
+    name: fn.getName() ?? sourceFile.getBaseNameWithoutExtension(),
+    filePath,
+    propsTypeName,
+    returnTypeName,
+    jsDocDescription: extractJsDoc(fn),
+  };
+}
+
+/**
+ * Extract loader info from an arrow function or function expression.
+ */
+function extractLoaderFromCallable(
+  fn: ArrowFunction | FunctionExpression,
+  name: string,
+  sourceFile: SourceFile,
+  filePath: string,
+): LoaderInfo | null {
+  const returnTypeText = fn.getReturnType().getText();
+
+  if (looksLikeJSX(returnTypeText)) return null;
+
+  let propsTypeName: string | null = null;
+  const params = fn.getParameters();
+  if (params.length > 0) {
+    const propsType = params[0].getType();
+    propsTypeName =
+      propsType.getAliasSymbol()?.getName() ??
+      propsType.getSymbol()?.getName() ??
+      null;
+  }
+
+  const returnTypeName = resolveReturnTypeName(returnTypeText);
+
+  return {
+    name: name || sourceFile.getBaseNameWithoutExtension(),
+    filePath,
+    propsTypeName,
+    returnTypeName,
+    jsDocDescription: extractJsDocFromParent(fn),
+  };
+}
+
+/**
+ * Resolve the return type name by unwrapping Promise<> and stripping nullable.
+ * Returns null if the type can't be resolved to a named type.
+ */
+function resolveReturnTypeName(returnTypeText: string): string | null {
+  const unwrapped = unwrapPromise(returnTypeText);
+  const core = stripNullable(unwrapped);
+
+  // If the core type is a primitive or empty, return null
+  if (
+    !core ||
+    core === "void" ||
+    core === "never" ||
+    core === "any" ||
+    core === "unknown"
+  ) {
+    return null;
+  }
+
+  // If it looks like an inline/anonymous type (starts with { or contains =>),
+  // return null since ts-json-schema-generator needs a named type
+  if (core.startsWith("{") || core.includes("=>")) {
+    return null;
+  }
+
+  return core;
+}
diff --git a/packages/mesh-plugin-site-editor/server/scanner/types.ts b/packages/mesh-plugin-site-editor/server/scanner/types.ts
index 195c691f60..55e5b7a026 100644
--- a/packages/mesh-plugin-site-editor/server/scanner/types.ts
+++ b/packages/mesh-plugin-site-editor/server/scanner/types.ts
@@ -116,3 +116,73 @@ export interface BlockSummary {
   /** Number of top-level props */
   propsCount: number;
 }
+
+// ---------------------------------------------------------------------------
+// Loader types
+// ---------------------------------------------------------------------------
+
+/**
+ * Loader function info extracted during discovery (analogous to ComponentInfo).
+ */
+export interface LoaderInfo {
+  /** Loader function name */
+  name: string;
+  /** Source file path within the project */
+  filePath: string;
+  /** TypeScript type name for the input Props parameter, or null */
+  propsTypeName: string | null;
+  /** TypeScript type name for the return type (unwrapped from Promise), or null */
+  returnTypeName: string | null;
+  /** JSDoc description */
+  jsDocDescription: string;
+}
+
+/**
+ * Full loader definition stored in .deco/loaders/{id}.json.
+ */
+export interface LoaderDefinition {
+  /** Unique ID derived from loader path, e.g., "loaders--productList" */
+  id: string;
+  /** Source file path, e.g., "loaders/productList.ts" */
+  source: string;
+  /** Human-readable label, e.g., "Product List" */
+  label: string;
+  /** Category derived from directory, e.g., "Loaders" */
+  category: string;
+  /** Description from JSDoc */
+  description: string;
+  /** JSON Schema for loader INPUT parameters (Props type) */
+  inputSchema: JSONSchema7;
+  /** JSON Schema for loader OUTPUT (return type) */
+  outputSchema: JSONSchema7;
+  /** Default input parameter values */
+  defaults: Record<string, unknown>;
+  /** Scan metadata */
+  metadata: {
+    scannedAt: string;
+    scanMethod: "ts-morph" | "manual" | "ai-agent";
+    propsTypeName: string | null;
+    returnTypeName: string | null;
+    customized: string[];
+  };
+}
+
+/**
+ * Lightweight loader summary for list operations.
+ */
+export interface LoaderSummary {
+  id: string;
+  source: string;
+  label: string;
+  category: string;
+  inputParamsCount: number;
+}
+
+/**
+ * Reference to a loader definition from a block instance prop value.
+ */
+export interface LoaderRef {
+  __loaderRef: string; // LoaderDefinition.id
+  field?: string; // Optional: pick a specific field from loader output
+  params?: Record<string, unknown>; // Configured input parameter values
+}

From d06bedc3380f33a764796e589d363fca59e1278a Mon Sep 17 00:00:00 2001
From: Guilherme Rodrigues <gui@deco.cx>
Date: Sat, 14 Feb 2026 11:01:06 -0300
Subject: [PATCH 17/26] feat(04-01): add loader server tools, client API, and
 query keys

- Add CMS_LOADER_SCAN tool: discovers loaders, generates input/output schemas, writes to .deco/loaders/
- Add CMS_LOADER_LIST tool: lists loader definitions with summaries
- Add CMS_LOADER_GET tool: reads full loader definition by ID
- Register all three tools in server/tools/index.ts
- Add client loader-api.ts with listLoaders and getLoader helpers via SITE_BINDING
- Add loaders namespace to query-keys.ts with all/detail keys

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../client/lib/loader-api.ts                  | 114 +++++++++
 .../client/lib/query-keys.ts                  |   9 +
 .../server/tools/index.ts                     |   7 +
 .../server/tools/loader-get.ts                |  76 ++++++
 .../server/tools/loader-list.ts               | 104 ++++++++
 .../server/tools/loader-scan.ts               | 240 ++++++++++++++++++
 6 files changed, 550 insertions(+)
 create mode 100644 packages/mesh-plugin-site-editor/client/lib/loader-api.ts
 create mode 100644 packages/mesh-plugin-site-editor/server/tools/loader-get.ts
 create mode 100644 packages/mesh-plugin-site-editor/server/tools/loader-list.ts
 create mode 100644 packages/mesh-plugin-site-editor/server/tools/loader-scan.ts

diff --git a/packages/mesh-plugin-site-editor/client/lib/loader-api.ts b/packages/mesh-plugin-site-editor/client/lib/loader-api.ts
new file mode 100644
index 0000000000..b3bad9cf5f
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/lib/loader-api.ts
@@ -0,0 +1,114 @@
+/**
+ * Loader API helpers
+ *
+ * Client-side loader listing and fetching using SITE_BINDING tools (LIST_FILES, READ_FILE).
+ * Follows the same pattern as block-api.ts -- calls through the plugin's toolCaller
+ * which is connected to the site's MCP.
+ */
+
+import type { TypedToolCaller } from "@decocms/bindings";
+import type { SiteBinding } from "@decocms/bindings/site";
+
+type ToolCaller = TypedToolCaller<SiteBinding>;
+
+/**
+ * Loader summary returned by list operations.
+ */
+export interface LoaderSummary {
+  id: string;
+  source: string;
+  label: string;
+  category: string;
+  inputParamsCount: number;
+}
+
+/**
+ * Full loader definition returned by get operations.
+ */
+export interface LoaderDefinition {
+  id: string;
+  source: string;
+  label: string;
+  category: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  outputSchema: Record<string, unknown>;
+  defaults: Record<string, unknown>;
+  metadata: {
+    scannedAt: string;
+    scanMethod: "ts-morph" | "manual" | "ai-agent";
+    propsTypeName: string | null;
+    returnTypeName: string | null;
+    customized: string[];
+  };
+}
+
+const LOADERS_PREFIX = ".deco/loaders/";
+
+/**
+ * List all loaders from .deco/loaders/
+ */
+export async function listLoaders(
+  toolCaller: ToolCaller,
+): Promise<LoaderSummary[]> {
+  const listResult = await toolCaller("LIST_FILES", {
+    prefix: LOADERS_PREFIX,
+  });
+
+  if (!listResult.files || listResult.files.length === 0) {
+    return [];
+  }
+
+  const loaders: LoaderSummary[] = [];
+
+  for (const file of listResult.files) {
+    if (!file.path.endsWith(".json")) continue;
+
+    try {
+      const readResult = await toolCaller("READ_FILE", { path: file.path });
+      const loader = JSON.parse(readResult.content);
+
+      if (loader.deleted) continue;
+
+      const inputParamsCount = Object.keys(
+        loader.inputSchema?.properties ?? {},
+      ).length;
+
+      loaders.push({
+        id: loader.id,
+        source: loader.source,
+        label: loader.label,
+        category: loader.category ?? "Other",
+        inputParamsCount,
+      });
+    } catch {
+      // Skip unreadable files
+      continue;
+    }
+  }
+
+  // Sort by label alphabetically
+  loaders.sort((a, b) => a.label.localeCompare(b.label));
+
+  return loaders;
+}
+
+/**
+ * Get a single loader definition by ID
+ */
+export async function getLoader(
+  toolCaller: ToolCaller,
+  loaderId: string,
+): Promise<LoaderDefinition | null> {
+  try {
+    const result = await toolCaller("READ_FILE", {
+      path: `${LOADERS_PREFIX}${loaderId}.json`,
+    });
+
+    const loader = JSON.parse(result.content);
+    if (loader.deleted) return null;
+    return loader;
+  } catch {
+    return null;
+  }
+}
diff --git a/packages/mesh-plugin-site-editor/client/lib/query-keys.ts b/packages/mesh-plugin-site-editor/client/lib/query-keys.ts
index c738531a9d..ab87173338 100644
--- a/packages/mesh-plugin-site-editor/client/lib/query-keys.ts
+++ b/packages/mesh-plugin-site-editor/client/lib/query-keys.ts
@@ -15,7 +15,16 @@ export const queryKeys = {
     detail: (connectionId: string, blockId: string) =>
       ["site-editor", "blocks", connectionId, blockId] as const,
   },
+  loaders: {
+    all: (connectionId: string) =>
+      ["site-editor", "loaders", connectionId] as const,
+    detail: (connectionId: string, loaderId: string) =>
+      ["site-editor", "loaders", connectionId, loaderId] as const,
+  },
 } as const;
 
 /** Shorthand for block query keys */
 export const blockKeys = queryKeys.blocks;
+
+/** Shorthand for loader query keys */
+export const loaderKeys = queryKeys.loaders;
diff --git a/packages/mesh-plugin-site-editor/server/tools/index.ts b/packages/mesh-plugin-site-editor/server/tools/index.ts
index 8d4ec38d93..3337d5d0d6 100644
--- a/packages/mesh-plugin-site-editor/server/tools/index.ts
+++ b/packages/mesh-plugin-site-editor/server/tools/index.ts
@@ -3,6 +3,7 @@
  *
  * Page CRUD tools for managing CMS pages stored in .deco/pages/.
  * Block scanner and management tools for .deco/blocks/.
+ * Loader scanner and management tools for .deco/loaders/.
  */
 
 import type { ServerPluginToolDefinition } from "@decocms/bindings/server-plugin";
@@ -15,6 +16,9 @@ import { BLOCK_SCAN } from "./block-scan";
 import { BLOCK_LIST } from "./block-list";
 import { BLOCK_GET } from "./block-get";
 import { BLOCK_REGISTER } from "./block-register";
+import { LOADER_SCAN } from "./loader-scan";
+import { LOADER_LIST } from "./loader-list";
+import { LOADER_GET } from "./loader-get";
 
 export const tools: ServerPluginToolDefinition[] = [
   PAGE_LIST,
@@ -26,4 +30,7 @@ export const tools: ServerPluginToolDefinition[] = [
   BLOCK_LIST,
   BLOCK_GET,
   BLOCK_REGISTER,
+  LOADER_SCAN,
+  LOADER_LIST,
+  LOADER_GET,
 ];
diff --git a/packages/mesh-plugin-site-editor/server/tools/loader-get.ts b/packages/mesh-plugin-site-editor/server/tools/loader-get.ts
new file mode 100644
index 0000000000..35f73b1d37
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/server/tools/loader-get.ts
@@ -0,0 +1,76 @@
+/**
+ * CMS_LOADER_GET Tool
+ *
+ * Reads a single loader definition by ID from .deco/loaders/{loaderId}.json via MCP.
+ * Returns the full LoaderDefinition including input and output JSON Schemas.
+ */
+
+import { z } from "zod";
+import type { ServerPluginToolDefinition } from "@decocms/bindings/server-plugin";
+
+export const LOADER_GET: ServerPluginToolDefinition = {
+  name: "CMS_LOADER_GET",
+  description:
+    "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({
+    loader: z
+      .object({
+        id: z.string(),
+        source: z.string(),
+        label: z.string(),
+        category: z.string(),
+        description: z.string(),
+        inputSchema: z.record(z.string(), z.unknown()),
+        outputSchema: z.record(z.string(), z.unknown()),
+        defaults: z.record(z.string(), z.unknown()),
+        metadata: z.object({
+          scannedAt: z.string(),
+          scanMethod: z.string(),
+          propsTypeName: z.string().nullable(),
+          returnTypeName: z.string().nullable(),
+          customized: z.array(z.string()),
+        }),
+      })
+      .nullable(),
+  }),
+
+  handler: async (input, ctx) => {
+    const { connectionId, loaderId } = input as {
+      connectionId: string;
+      loaderId: string;
+    };
+    const proxy = await ctx.createMCPProxy(connectionId);
+
+    try {
+      const readResult = await proxy.callTool({
+        name: "READ_FILE",
+        arguments: { path: `.deco/loaders/${loaderId}.json` },
+      });
+
+      if (readResult.isError) {
+        return { loader: null };
+      }
+
+      const content = readResult.content?.[0]?.text;
+      if (!content) {
+        return { loader: null };
+      }
+
+      try {
+        const loader = JSON.parse(content);
+        if (loader.deleted) {
+          return { loader: null };
+        }
+        return { loader };
+      } catch {
+        return { loader: null };
+      }
+    } finally {
+      await proxy.close?.();
+    }
+  },
+};
diff --git a/packages/mesh-plugin-site-editor/server/tools/loader-list.ts b/packages/mesh-plugin-site-editor/server/tools/loader-list.ts
new file mode 100644
index 0000000000..34636793a6
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/server/tools/loader-list.ts
@@ -0,0 +1,104 @@
+/**
+ * CMS_LOADER_LIST Tool
+ *
+ * Lists all loader definitions from .deco/loaders/ via MCP file operations.
+ * Returns summaries with id, source, label, category, and input param count.
+ */
+
+import { z } from "zod";
+import type { ServerPluginToolDefinition } from "@decocms/bindings/server-plugin";
+
+export const LOADER_LIST: ServerPluginToolDefinition = {
+  name: "CMS_LOADER_LIST",
+  description:
+    "List all CMS loader definitions with their metadata (id, source, label, category, inputParamsCount).",
+  inputSchema: z.object({
+    connectionId: z.string().describe("MCP connection ID for the site"),
+  }),
+  outputSchema: z.object({
+    loaders: z.array(
+      z.object({
+        id: z.string(),
+        source: z.string(),
+        label: z.string(),
+        category: z.string(),
+        inputParamsCount: z.number(),
+      }),
+    ),
+  }),
+
+  handler: async (input, ctx) => {
+    const { connectionId } = input as { connectionId: string };
+    const proxy = await ctx.createMCPProxy(connectionId);
+
+    try {
+      const listResult = await proxy.callTool({
+        name: "LIST_FILES",
+        arguments: { prefix: ".deco/loaders/" },
+      });
+
+      const listContent = listResult.content?.[0]?.text;
+      if (!listContent) {
+        return { loaders: [] };
+      }
+
+      let fileList: { files?: Array<{ path: string }>; count?: number };
+      try {
+        fileList = JSON.parse(listContent);
+      } catch {
+        return { loaders: [] };
+      }
+
+      if (!fileList.files || fileList.files.length === 0) {
+        return { loaders: [] };
+      }
+
+      const loaders: Array<{
+        id: string;
+        source: string;
+        label: string;
+        category: string;
+        inputParamsCount: number;
+      }> = [];
+
+      for (const file of fileList.files) {
+        if (!file.path.endsWith(".json")) continue;
+
+        try {
+          const readResult = await proxy.callTool({
+            name: "READ_FILE",
+            arguments: { path: file.path },
+          });
+
+          const content = readResult.content?.[0]?.text;
+          if (!content) continue;
+
+          const loader = JSON.parse(content);
+          if (loader.deleted) continue; // Skip tombstoned loaders
+
+          const inputParamsCount = Object.keys(
+            loader.inputSchema?.properties ?? {},
+          ).length;
+
+          loaders.push({
+            id: loader.id,
+            source: loader.source,
+            label: loader.label,
+            category: loader.category ?? "Other",
+            inputParamsCount,
+          });
+        } catch {
+          // Skip files that can't be read or parsed
+          continue;
+        }
+      }
+
+      // Sort by label alphabetically
+      loaders.sort((a, b) => a.label.localeCompare(b.label));
+
+      return { loaders };
+    } finally {
+      await proxy.close?.();
+    }
+  },
+};
diff --git a/packages/mesh-plugin-site-editor/server/tools/loader-scan.ts b/packages/mesh-plugin-site-editor/server/tools/loader-scan.ts
new file mode 100644
index 0000000000..d5df8c8259
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/server/tools/loader-scan.ts
@@ -0,0 +1,240 @@
+/**
+ * CMS_LOADER_SCAN Tool
+ *
+ * Scans a site's TypeScript codebase via MCP to discover loader functions,
+ * generate JSON Schema for their input params and output, and write loader
+ * definitions to .deco/loaders/.
+ *
+ * Pipeline: createProjectFromMCP -> discoverLoaders -> generateSchema -> write loaders
+ */
+
+import { z } from "zod";
+import type { ServerPluginToolDefinition } from "@decocms/bindings/server-plugin";
+import { createProjectFromMCP } from "../scanner/extract.js";
+import { discoverLoaders } from "../scanner/discover.js";
+import { generateSchema } from "../scanner/schema.js";
+import type { LoaderDefinition, LoaderSummary } from "../scanner/types.js";
+
+const DEFAULT_PATTERNS = ["loaders/"];
+
+/**
+ * Derive a loader ID from a source path.
+ * e.g., "loaders/productList.ts" -> "loaders--productList"
+ */
+function sourceToId(source: string): string {
+  return source
+    .replace(/\.\w+$/, "") // strip extension
+    .replace(/\//g, "--"); // replace / with --
+}
+
+/**
+ * Convert a loader name to a human-readable label.
+ * e.g., "productList" -> "Product List"
+ */
+function nameToLabel(name: string): string {
+  return name.replace(/([a-z])([A-Z])/g, "$1 $2");
+}
+
+/**
+ * Derive category from the first directory segment.
+ * e.g., "loaders/productList.ts" -> "Loaders"
+ */
+function sourceToCategory(source: string): string {
+  const firstSegment = source.split("/")[0] ?? "Other";
+  return firstSegment.charAt(0).toUpperCase() + firstSegment.slice(1);
+}
+
+export const LOADER_SCAN: ServerPluginToolDefinition = {
+  name: "CMS_LOADER_SCAN",
+  description:
+    "Scan a site's TypeScript codebase and generate loader definitions in .deco/loaders/",
+  inputSchema: z.object({
+    connectionId: z.string().describe("MCP connection ID for the site"),
+    patterns: z
+      .array(z.string())
+      .optional()
+      .describe("File path prefixes to scan (default: ['loaders/'])"),
+  }),
+  outputSchema: z.object({
+    loaders: z.array(
+      z.object({
+        id: z.string(),
+        source: z.string(),
+        label: z.string(),
+        category: z.string(),
+        inputParamsCount: z.number(),
+      }),
+    ),
+    errors: z.array(z.string()),
+  }),
+
+  handler: async (input, ctx) => {
+    const { connectionId, patterns = DEFAULT_PATTERNS } = input as {
+      connectionId: string;
+      patterns?: string[];
+    };
+    const proxy = await ctx.createMCPProxy(connectionId);
+
+    const loaders: LoaderSummary[] = [];
+    const errors: string[] = [];
+
+    try {
+      // 1. Build in-memory ts-morph project from MCP files
+      const project = await createProjectFromMCP(proxy, patterns);
+
+      // 2. Discover loaders
+      const discovered = discoverLoaders(project);
+
+      // 3. For each loader, generate schemas and write loader definition
+      for (const loader of discovered) {
+        try {
+          // Normalize the source path (strip leading /)
+          const source = loader.filePath.startsWith("/")
+            ? loader.filePath.slice(1)
+            : loader.filePath;
+          const id = sourceToId(source);
+          const label = nameToLabel(loader.name);
+          const category = sourceToCategory(source);
+
+          // Generate JSON Schema for input params (Props type)
+          let inputSchema: Record<string, unknown> = {
+            type: "object",
+            properties: {},
+            additionalProperties: false,
+          };
+          if (loader.propsTypeName) {
+            inputSchema = generateSchema(
+              project,
+              loader.propsTypeName,
+              loader.filePath,
+            ) as typeof inputSchema;
+          }
+
+          // Generate JSON Schema for output (return type)
+          let outputSchema: Record<string, unknown> = {
+            type: "object",
+            additionalProperties: true,
+          };
+          if (loader.returnTypeName) {
+            outputSchema = generateSchema(
+              project,
+              loader.returnTypeName,
+              loader.filePath,
+            ) as typeof outputSchema;
+          }
+
+          const inputParamsCount = Object.keys(
+            (inputSchema as Record<string, unknown>).properties ?? {},
+          ).length;
+
+          // Build loader definition, merging with existing if needed
+          const loaderDef = await buildLoaderDefinition(
+            proxy,
+            id,
+            source,
+            label,
+            category,
+            loader.jsDocDescription,
+            inputSchema,
+            outputSchema,
+            loader.propsTypeName,
+            loader.returnTypeName,
+          );
+
+          // Write loader definition
+          await proxy.callTool({
+            name: "PUT_FILE",
+            arguments: {
+              path: `.deco/loaders/${id}.json`,
+              content: JSON.stringify(loaderDef, null, 2),
+            },
+          });
+
+          loaders.push({ id, source, label, category, inputParamsCount });
+        } catch (err) {
+          errors.push(
+            `Failed to process ${loader.name}: ${err instanceof Error ? err.message : String(err)}`,
+          );
+        }
+      }
+    } catch (err) {
+      errors.push(
+        `Scan failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    } finally {
+      await proxy.close?.();
+    }
+
+    return { loaders, errors };
+  },
+};
+
+/**
+ * Build a LoaderDefinition, merging with existing data if user has customized fields.
+ */
+async function buildLoaderDefinition(
+  // deno-lint-ignore no-explicit-any
+  proxy: any,
+  id: string,
+  source: string,
+  label: string,
+  category: string,
+  description: string,
+  inputSchema: Record<string, unknown>,
+  outputSchema: Record<string, unknown>,
+  propsTypeName: string | null,
+  returnTypeName: string | null,
+): Promise<LoaderDefinition> {
+  const now = new Date().toISOString();
+
+  const newDef: LoaderDefinition = {
+    id,
+    source,
+    label,
+    category,
+    description,
+    inputSchema,
+    outputSchema,
+    defaults: {},
+    metadata: {
+      scannedAt: now,
+      scanMethod: "ts-morph",
+      propsTypeName,
+      returnTypeName,
+      customized: [],
+    },
+  };
+
+  // Try to read existing loader to preserve customized fields
+  try {
+    const readResult = await proxy.callTool({
+      name: "READ_FILE",
+      arguments: { path: `.deco/loaders/${id}.json` },
+    });
+
+    const content = readResult.content?.[0]?.text;
+    if (content) {
+      const existing = JSON.parse(content) as LoaderDefinition;
+      const customized = existing.metadata?.customized ?? [];
+
+      if (customized.length > 0) {
+        // Preserve user-customized fields
+        if (customized.includes("label")) newDef.label = existing.label;
+        if (customized.includes("description")) {
+          newDef.description = existing.description;
+        }
+        if (customized.includes("category")) {
+          newDef.category = existing.category;
+        }
+        if (customized.includes("defaults")) {
+          newDef.defaults = existing.defaults;
+        }
+        newDef.metadata.customized = customized;
+      }
+    }
+  } catch {
+    // No existing loader -- use new definition as-is
+  }
+
+  return newDef;
+}

From 6bf04b06ea643bddff9448508473e1c24e147154 Mon Sep 17 00:00:00 2001
From: Guilherme Rodrigues <gui@deco.cx>
Date: Sat, 14 Feb 2026 11:06:33 -0300
Subject: [PATCH 18/26] feat(04-02): loaders list and detail views with router
 wiring

- Replace loaders-list stub with full categorized list using loader-api
- Create loader-detail with metadata, output schema, and PropEditor for input params
- Add /loaders/$loaderId route to plugin router

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../client/components/loader-detail.tsx       | 273 ++++++++++++++++++
 .../client/components/loaders-list.tsx        | 151 +++++++++-
 .../client/lib/router.ts                      |   7 +
 3 files changed, 424 insertions(+), 7 deletions(-)
 create mode 100644 packages/mesh-plugin-site-editor/client/components/loader-detail.tsx

diff --git a/packages/mesh-plugin-site-editor/client/components/loader-detail.tsx b/packages/mesh-plugin-site-editor/client/components/loader-detail.tsx
new file mode 100644
index 0000000000..52811e9677
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/components/loader-detail.tsx
@@ -0,0 +1,273 @@
+/**
+ * Loader Detail Component
+ *
+ * Shows loader metadata, output schema, and an @rjsf prop editor for input parameters.
+ * Uses SITE_BINDING tools via loader-api helpers.
+ * This is a browsing/exploration view -- actual parameter configuration happens
+ * when binding a loader to a section prop via the loader picker.
+ */
+
+import { useRef, useState } from "react";
+import { SITE_BINDING } from "@decocms/bindings/site";
+import { usePluginContext } from "@decocms/mesh-sdk/plugins";
+import { useQuery } from "@tanstack/react-query";
+import { Button } from "@deco/ui/components/button.tsx";
+import { Badge } from "@deco/ui/components/badge.tsx";
+import { ArrowLeft, Loading01, AlertCircle } from "@untitledui/icons";
+import { ChevronDown, ChevronRight } from "lucide-react";
+import { loaderKeys } from "../lib/query-keys";
+import { siteEditorRouter } from "../lib/router";
+import { getLoader } from "../lib/loader-api";
+import { PropEditor } from "./prop-editor";
+
+function formatTimestamp(dateStr: string): string {
+  if (!dateStr) return "-";
+  try {
+    return new Date(dateStr).toLocaleString(undefined, {
+      year: "numeric",
+      month: "short",
+      day: "numeric",
+      hour: "2-digit",
+      minute: "2-digit",
+    });
+  } catch {
+    return dateStr;
+  }
+}
+
+function scanMethodLabel(method: string): string {
+  switch (method) {
+    case "ts-morph":
+      return "ts-morph";
+    case "manual":
+      return "Manual";
+    case "ai-agent":
+      return "AI Agent";
+    default:
+      return method;
+  }
+}
+
+export default function LoaderDetail() {
+  const { toolCaller, connectionId } = usePluginContext<typeof SITE_BINDING>();
+  const navigate = siteEditorRouter.useNavigate();
+  const { loaderId } = siteEditorRouter.useParams({
+    from: "/loaders/$loaderId",
+  });
+
+  const [formData, setFormData] = useState<Record<string, unknown>>({});
+  const [outputSchemaExpanded, setOutputSchemaExpanded] = useState(false);
+  const [inputSchemaExpanded, setInputSchemaExpanded] = useState(false);
+  const lastSyncedLoaderId = useRef<string | null>(null);
+
+  const {
+    data: loader,
+    isLoading,
+    error,
+  } = useQuery({
+    queryKey: loaderKeys.detail(connectionId, loaderId),
+    queryFn: () => getLoader(toolCaller, loaderId),
+  });
+
+  // Sync formData when loader data loads (ref-based, not useEffect)
+  if (loader && lastSyncedLoaderId.current !== loader.id) {
+    lastSyncedLoaderId.current = loader.id;
+    setFormData(loader.defaults ?? {});
+  }
+
+  if (isLoading) {
+    return (
+      <div className="flex flex-col items-center justify-center h-full p-8">
+        <Loading01
+          size={32}
+          className="animate-spin text-muted-foreground mb-4"
+        />
+        <p className="text-sm text-muted-foreground">Loading loader...</p>
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className="flex flex-col items-center justify-center h-full p-8">
+        <AlertCircle size={48} className="text-destructive mb-4" />
+        <h3 className="text-lg font-medium mb-2">Error loading loader</h3>
+        <p className="text-muted-foreground text-center">
+          {error instanceof Error ? error.message : "Unknown error"}
+        </p>
+      </div>
+    );
+  }
+
+  if (!loader) {
+    return (
+      <div className="flex flex-col items-center justify-center h-full p-8">
+        <AlertCircle size={48} className="text-muted-foreground mb-4" />
+        <h3 className="text-lg font-medium mb-2">Loader not found</h3>
+        <p className="text-muted-foreground text-center mb-4">
+          The loader &quot;{loaderId}&quot; could not be found.
+        </p>
+        <Button variant="outline" onClick={() => navigate({ to: "/loaders" })}>
+          <ArrowLeft size={14} className="mr-1" />
+          Back to Loaders
+        </Button>
+      </div>
+    );
+  }
+
+  const inputParamsCount = Object.keys(
+    loader.inputSchema?.properties ?? {},
+  ).length;
+  const hasInputSchema =
+    loader.inputSchema &&
+    typeof loader.inputSchema === "object" &&
+    Object.keys(loader.inputSchema).length > 0;
+  const hasOutputSchema =
+    loader.outputSchema &&
+    typeof loader.outputSchema === "object" &&
+    Object.keys(loader.outputSchema).length > 0;
+
+  return (
+    <div className="flex flex-col h-full">
+      {/* Header with breadcrumb */}
+      <div className="flex items-center justify-between px-4 py-3 border-b border-border bg-background">
+        <div className="flex items-center gap-2 text-sm">
+          <button
+            type="button"
+            onClick={() => navigate({ to: "/loaders" })}
+            className="text-muted-foreground hover:text-foreground transition-colors"
+          >
+            Loaders
+          </button>
+          <span className="text-muted-foreground">/</span>
+          <span className="font-medium">{loader.label}</span>
+        </div>
+      </div>
+
+      {/* Content */}
+      <div className="flex-1 overflow-y-auto p-6">
+        <div className="max-w-2xl space-y-6">
+          {/* Loader info */}
+          <div>
+            <h2 className="text-xl font-semibold">{loader.label}</h2>
+            <p className="text-sm text-muted-foreground mt-1">
+              {loader.source}
+            </p>
+            {loader.description && (
+              <p className="text-sm text-muted-foreground mt-2">
+                {loader.description}
+              </p>
+            )}
+          </div>
+
+          {/* Metadata section */}
+          <div className="border border-border rounded-lg p-4 space-y-3">
+            <h3 className="text-sm font-medium text-muted-foreground">
+              Metadata
+            </h3>
+            <div className="grid grid-cols-2 gap-3 text-sm">
+              <div>
+                <span className="text-muted-foreground">Scan Method</span>
+                <div className="mt-0.5">
+                  <Badge variant="secondary" className="text-xs">
+                    {scanMethodLabel(loader.metadata.scanMethod)}
+                  </Badge>
+                </div>
+              </div>
+              <div>
+                <span className="text-muted-foreground">Scanned</span>
+                <p className="mt-0.5">
+                  {formatTimestamp(loader.metadata.scannedAt)}
+                </p>
+              </div>
+              <div>
+                <span className="text-muted-foreground">Props Type</span>
+                <p className="font-mono text-xs mt-0.5">
+                  {loader.metadata.propsTypeName ?? "none"}
+                </p>
+              </div>
+              <div>
+                <span className="text-muted-foreground">Return Type</span>
+                <p className="font-mono text-xs mt-0.5">
+                  {loader.metadata.returnTypeName ?? "unknown"}
+                </p>
+              </div>
+              <div>
+                <span className="text-muted-foreground">Input Params</span>
+                <p className="mt-0.5">{inputParamsCount} params</p>
+              </div>
+            </div>
+          </div>
+
+          {/* Output schema (collapsible) */}
+          {hasOutputSchema && (
+            <div className="border border-border rounded-lg">
+              <button
+                type="button"
+                onClick={() => setOutputSchemaExpanded(!outputSchemaExpanded)}
+                className="flex items-center gap-2 w-full px-4 py-3 text-sm font-medium text-muted-foreground hover:text-foreground transition-colors"
+              >
+                {outputSchemaExpanded ? (
+                  <ChevronDown size={14} />
+                ) : (
+                  <ChevronRight size={14} />
+                )}
+                Output Schema
+              </button>
+              {outputSchemaExpanded && (
+                <div className="border-t border-border px-4 py-3">
+                  <pre className="text-xs font-mono overflow-x-auto bg-muted/30 rounded p-3 max-h-80 overflow-y-auto">
+                    {JSON.stringify(loader.outputSchema, null, 2)}
+                  </pre>
+                </div>
+              )}
+            </div>
+          )}
+
+          {/* Input schema raw view (collapsible) */}
+          {hasInputSchema && (
+            <div className="border border-border rounded-lg">
+              <button
+                type="button"
+                onClick={() => setInputSchemaExpanded(!inputSchemaExpanded)}
+                className="flex items-center gap-2 w-full px-4 py-3 text-sm font-medium text-muted-foreground hover:text-foreground transition-colors"
+              >
+                {inputSchemaExpanded ? (
+                  <ChevronDown size={14} />
+                ) : (
+                  <ChevronRight size={14} />
+                )}
+                Raw Input Schema
+              </button>
+              {inputSchemaExpanded && (
+                <div className="border-t border-border px-4 py-3">
+                  <pre className="text-xs font-mono overflow-x-auto bg-muted/30 rounded p-3 max-h-80 overflow-y-auto">
+                    {JSON.stringify(loader.inputSchema, null, 2)}
+                  </pre>
+                </div>
+              )}
+            </div>
+          )}
+
+          {/* Input Parameters editor */}
+          {hasInputSchema && inputParamsCount > 0 ? (
+            <div className="space-y-3">
+              <h3 className="text-sm font-medium">Input Parameters</h3>
+              <div className="border border-border rounded-lg p-4">
+                <PropEditor
+                  schema={loader.inputSchema as any}
+                  formData={formData}
+                  onChange={setFormData}
+                />
+              </div>
+            </div>
+          ) : (
+            <div className="text-center py-8 text-muted-foreground text-sm">
+              This loader has no input parameters.
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/packages/mesh-plugin-site-editor/client/components/loaders-list.tsx b/packages/mesh-plugin-site-editor/client/components/loaders-list.tsx
index 0b8f85e229..bb7d5d990d 100644
--- a/packages/mesh-plugin-site-editor/client/components/loaders-list.tsx
+++ b/packages/mesh-plugin-site-editor/client/components/loaders-list.tsx
@@ -1,17 +1,154 @@
 /**
  * Loaders List Component
  *
- * Displays the list of loaders managed by the site editor.
- * Full implementation will be added in later plans.
+ * Displays all scanned loaders grouped by category.
+ * Navigates to loader detail view on click.
+ * Uses SITE_BINDING tools (LIST_FILES, READ_FILE) via loader-api helpers.
  */
 
+import { SITE_BINDING } from "@decocms/bindings/site";
+import { usePluginContext } from "@decocms/mesh-sdk/plugins";
+import { useQuery } from "@tanstack/react-query";
+import { Button } from "@deco/ui/components/button.tsx";
+import { Badge } from "@deco/ui/components/badge.tsx";
+import { AlertCircle, Loading01 } from "@untitledui/icons";
+import { Database, Search } from "lucide-react";
+import { loaderKeys } from "../lib/query-keys";
+import { siteEditorRouter } from "../lib/router";
+import { listLoaders } from "../lib/loader-api";
+import type { LoaderSummary } from "../lib/loader-api";
+
+/**
+ * Group loaders by category, sorted alphabetically within each group.
+ */
+function groupByCategory(
+  loaders: LoaderSummary[],
+): Record<string, LoaderSummary[]> {
+  const groups: Record<string, LoaderSummary[]> = {};
+  for (const loader of loaders) {
+    const category = loader.category || "Other";
+    if (!groups[category]) {
+      groups[category] = [];
+    }
+    groups[category].push(loader);
+  }
+  // Sort loaders within each category
+  for (const category of Object.keys(groups)) {
+    groups[category].sort((a, b) => a.label.localeCompare(b.label));
+  }
+  return groups;
+}
+
 export default function LoadersList() {
+  const { toolCaller, connectionId } = usePluginContext<typeof SITE_BINDING>();
+  const navigate = siteEditorRouter.useNavigate();
+
+  const {
+    data: loaders = [],
+    isLoading,
+    error,
+  } = useQuery({
+    queryKey: loaderKeys.all(connectionId),
+    queryFn: () => listLoaders(toolCaller),
+  });
+
+  if (error) {
+    return (
+      <div className="flex flex-col items-center justify-center h-full p-8">
+        <AlertCircle size={48} className="text-destructive mb-4" />
+        <h3 className="text-lg font-medium mb-2">Error loading loaders</h3>
+        <p className="text-muted-foreground text-center">
+          {error instanceof Error ? error.message : "Unknown error"}
+        </p>
+      </div>
+    );
+  }
+
+  const grouped = groupByCategory(loaders);
+  const categoryNames = Object.keys(grouped).sort();
+
   return (
-    <div className="flex flex-col items-center justify-center h-full p-8">
-      <h3 className="text-lg font-medium mb-2">Loaders</h3>
-      <p className="text-muted-foreground text-center max-w-md">
-        Loaders will appear here once file listing is implemented.
-      </p>
+    <div className="flex flex-col h-full">
+      {/* Header */}
+      <div className="flex items-center justify-between px-4 py-3 border-b border-border bg-background">
+        <h2 className="text-sm font-medium">Loaders</h2>
+        <Badge variant="secondary" className="text-xs">
+          {loaders.length} loaders
+        </Badge>
+      </div>
+
+      {/* Loader list */}
+      <div className="flex-1 overflow-y-auto">
+        {isLoading ? (
+          <div className="flex flex-col items-center justify-center py-12">
+            <Loading01
+              size={32}
+              className="animate-spin text-muted-foreground mb-4"
+            />
+            <p className="text-sm text-muted-foreground">Loading loaders...</p>
+          </div>
+        ) : loaders.length === 0 ? (
+          <div className="flex flex-col items-center justify-center py-12 text-center px-6">
+            <Search size={48} className="text-muted-foreground mb-4" />
+            <h3 className="text-lg font-medium mb-2">No loaders found</h3>
+            <p className="text-muted-foreground mb-4 max-w-sm">
+              Scan your codebase to discover data loaders and generate editable
+              parameter forms automatically.
+            </p>
+            <Button
+              variant="outline"
+              onClick={() => {
+                console.log(
+                  "[site-editor] Loader scan trigger placeholder -- wire to CMS_LOADER_SCAN",
+                );
+              }}
+            >
+              <Search size={14} className="mr-1" />
+              Scan Codebase
+            </Button>
+          </div>
+        ) : (
+          categoryNames.map((category) => (
+            <div key={category}>
+              {/* Category header */}
+              <div className="px-4 py-2 text-xs font-medium text-muted-foreground uppercase tracking-wider bg-muted/30 border-b border-border">
+                {category}
+              </div>
+
+              {/* Loaders in category */}
+              {grouped[category].map((loader) => (
+                <button
+                  key={loader.id}
+                  type="button"
+                  onClick={() =>
+                    navigate({
+                      to: "/loaders/$loaderId",
+                      params: { loaderId: loader.id },
+                    })
+                  }
+                  className="group flex items-center gap-3 px-4 py-2.5 w-full text-left hover:bg-muted/50 border-b border-border last:border-b-0 transition-colors"
+                >
+                  <Database
+                    size={16}
+                    className="text-muted-foreground shrink-0"
+                  />
+                  <div className="flex-1 min-w-0">
+                    <span className="truncate font-medium text-sm block">
+                      {loader.label}
+                    </span>
+                    <span className="text-xs text-muted-foreground truncate block">
+                      {loader.source}
+                    </span>
+                  </div>
+                  <Badge variant="outline" className="text-xs shrink-0">
+                    {loader.inputParamsCount} params
+                  </Badge>
+                </button>
+              ))}
+            </div>
+          ))
+        )}
+      </div>
     </div>
   );
 }
diff --git a/packages/mesh-plugin-site-editor/client/lib/router.ts b/packages/mesh-plugin-site-editor/client/lib/router.ts
index 423f6a14e7..12e73e117a 100644
--- a/packages/mesh-plugin-site-editor/client/lib/router.ts
+++ b/packages/mesh-plugin-site-editor/client/lib/router.ts
@@ -43,11 +43,18 @@ export const siteEditorRouter = createPluginRouter((ctx) => {
     component: lazyRouteComponent(() => import("../components/loaders-list")),
   });
 
+  const loaderDetailRoute = createRoute({
+    getParentRoute: () => ctx.parentRoute,
+    path: "/loaders/$loaderId",
+    component: lazyRouteComponent(() => import("../components/loader-detail")),
+  });
+
   return [
     pagesRoute,
     pageEditorRoute,
     sectionsRoute,
     blockDetailRoute,
     loadersRoute,
+    loaderDetailRoute,
   ];
 });

From b71a254bd4631ceb82c7285b5843736c78bb62f9 Mon Sep 17 00:00:00 2001
From: Guilherme Rodrigues <gui@deco.cx>
Date: Sat, 14 Feb 2026 11:08:09 -0300
Subject: [PATCH 19/26] feat(04-02): loader picker modal and prop binding in
 page composer

- Add LoaderRef type and isLoaderRef guard to page-api
- Create loader-picker modal with category grouping and search filter
- Integrate loader binding into page-composer prop editing panel
- Show existing bindings with remove option, bind-to-prop links for each schema prop

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../client/components/loader-picker.tsx       | 183 ++++++++++++++++++
 .../client/components/page-composer.tsx       | 120 +++++++++++-
 .../client/lib/page-api.ts                    |  19 ++
 3 files changed, 321 insertions(+), 1 deletion(-)
 create mode 100644 packages/mesh-plugin-site-editor/client/components/loader-picker.tsx

diff --git a/packages/mesh-plugin-site-editor/client/components/loader-picker.tsx b/packages/mesh-plugin-site-editor/client/components/loader-picker.tsx
new file mode 100644
index 0000000000..c73dda2ad0
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/components/loader-picker.tsx
@@ -0,0 +1,183 @@
+/**
+ * Loader Picker Component
+ *
+ * Modal dialog for selecting a loader to bind to a section prop.
+ * Lists available loaders grouped by category with a search filter.
+ * Uses @deco/ui Dialog and fetches loaders via loader-api helpers.
+ */
+
+import { useState } from "react";
+import { SITE_BINDING } from "@decocms/bindings/site";
+import { usePluginContext } from "@decocms/mesh-sdk/plugins";
+import { useQuery } from "@tanstack/react-query";
+import {
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+} from "@deco/ui/components/dialog.tsx";
+import { Input } from "@deco/ui/components/input.tsx";
+import { Badge } from "@deco/ui/components/badge.tsx";
+import { cn } from "@deco/ui/lib/utils.ts";
+import { Database, Search } from "lucide-react";
+import { Loading01 } from "@untitledui/icons";
+import { loaderKeys } from "../lib/query-keys";
+import { listLoaders } from "../lib/loader-api";
+import type { LoaderSummary } from "../lib/loader-api";
+import type { LoaderRef } from "../lib/page-api";
+
+interface LoaderPickerProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  onSelect: (loaderRef: LoaderRef) => void;
+  propName: string;
+}
+
+/**
+ * Group loaders by category, sorted alphabetically within each group.
+ */
+function groupByCategory(
+  loaders: LoaderSummary[],
+): Record<string, LoaderSummary[]> {
+  const groups: Record<string, LoaderSummary[]> = {};
+  for (const loader of loaders) {
+    const category = loader.category || "Other";
+    if (!groups[category]) {
+      groups[category] = [];
+    }
+    groups[category].push(loader);
+  }
+  for (const category of Object.keys(groups)) {
+    groups[category].sort((a, b) => a.label.localeCompare(b.label));
+  }
+  return groups;
+}
+
+export function LoaderPicker({
+  open,
+  onOpenChange,
+  onSelect,
+  propName,
+}: LoaderPickerProps) {
+  const { toolCaller, connectionId } = usePluginContext<typeof SITE_BINDING>();
+  const [filter, setFilter] = useState("");
+
+  const { data: loaders = [], isLoading } = useQuery({
+    queryKey: loaderKeys.all(connectionId),
+    queryFn: () => listLoaders(toolCaller),
+    enabled: open,
+  });
+
+  // Filter loaders by search term
+  const filtered = filter
+    ? loaders.filter(
+        (l) =>
+          l.label.toLowerCase().includes(filter.toLowerCase()) ||
+          l.source.toLowerCase().includes(filter.toLowerCase()) ||
+          l.category.toLowerCase().includes(filter.toLowerCase()),
+      )
+    : loaders;
+
+  const grouped = groupByCategory(filtered);
+  const categoryNames = Object.keys(grouped).sort();
+
+  const handleSelect = (loader: LoaderSummary) => {
+    const loaderRef: LoaderRef = {
+      __loaderRef: loader.id,
+      params: {},
+    };
+    onSelect(loaderRef);
+    onOpenChange(false);
+    setFilter("");
+  };
+
+  const handleOpenChange = (isOpen: boolean) => {
+    if (!isOpen) {
+      setFilter("");
+    }
+    onOpenChange(isOpen);
+  };
+
+  return (
+    <Dialog open={open} onOpenChange={handleOpenChange}>
+      <DialogContent className="sm:max-w-lg max-h-[70vh] flex flex-col">
+        <DialogHeader>
+          <DialogTitle>Bind Loader to {propName}</DialogTitle>
+        </DialogHeader>
+
+        {/* Search filter */}
+        <div className="relative">
+          <Search
+            size={14}
+            className="absolute left-3 top-1/2 -translate-y-1/2 text-muted-foreground"
+          />
+          <Input
+            placeholder="Search loaders..."
+            value={filter}
+            onChange={(e) => setFilter(e.target.value)}
+            className="pl-9"
+          />
+        </div>
+
+        {/* Loader list */}
+        <div className="flex-1 overflow-y-auto -mx-6 px-6">
+          {isLoading ? (
+            <div className="flex flex-col items-center justify-center py-8">
+              <Loading01
+                size={24}
+                className="animate-spin text-muted-foreground mb-2"
+              />
+              <p className="text-sm text-muted-foreground">
+                Loading loaders...
+              </p>
+            </div>
+          ) : filtered.length === 0 ? (
+            <div className="flex flex-col items-center justify-center py-8">
+              <Search size={32} className="text-muted-foreground mb-2" />
+              <p className="text-sm text-muted-foreground">
+                {filter
+                  ? "No loaders match your search"
+                  : "No loaders available"}
+              </p>
+            </div>
+          ) : (
+            categoryNames.map((category) => (
+              <div key={category} className="mb-3">
+                <div className="text-xs font-medium text-muted-foreground uppercase tracking-wider py-1.5">
+                  {category}
+                </div>
+                {grouped[category].map((loader) => (
+                  <button
+                    key={loader.id}
+                    type="button"
+                    onClick={() => handleSelect(loader)}
+                    className={cn(
+                      "flex items-center gap-3 w-full text-left px-3 py-2 rounded transition-colors",
+                      "hover:bg-muted/50",
+                    )}
+                  >
+                    <Database
+                      size={16}
+                      className="text-muted-foreground shrink-0"
+                    />
+                    <div className="flex-1 min-w-0">
+                      <span className="text-sm font-medium block truncate">
+                        {loader.label}
+                      </span>
+                      <span className="text-xs text-muted-foreground block truncate">
+                        {loader.source}
+                      </span>
+                    </div>
+                    <Badge variant="outline" className="text-xs shrink-0">
+                      {loader.inputParamsCount} params
+                    </Badge>
+                  </button>
+                ))}
+              </div>
+            ))
+          )}
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}
diff --git a/packages/mesh-plugin-site-editor/client/components/page-composer.tsx b/packages/mesh-plugin-site-editor/client/components/page-composer.tsx
index 7bc7407d7f..d9f9780644 100644
--- a/packages/mesh-plugin-site-editor/client/components/page-composer.tsx
+++ b/packages/mesh-plugin-site-editor/client/components/page-composer.tsx
@@ -28,7 +28,13 @@ import {
 import { toast } from "sonner";
 import { queryKeys } from "../lib/query-keys";
 import { siteEditorRouter } from "../lib/router";
-import { getPage, updatePage, type BlockInstance } from "../lib/page-api";
+import {
+  getPage,
+  updatePage,
+  isLoaderRef,
+  type BlockInstance,
+  type LoaderRef,
+} from "../lib/page-api";
 import { getBlock } from "../lib/block-api";
 import { useEditorMessages } from "../lib/use-editor-messages";
 import { useUndoRedo } from "../lib/use-undo-redo";
@@ -37,6 +43,7 @@ import { ViewportToggle, type ViewportKey } from "./viewport-toggle";
 import { PropEditor } from "./prop-editor";
 import { SectionListSidebar } from "./section-list-sidebar";
 import { BlockPicker } from "./block-picker";
+import { LoaderPicker } from "./loader-picker";
 
 export default function PageComposer() {
   const { toolCaller, connectionId } = usePluginContext<typeof SITE_BINDING>();
@@ -47,6 +54,10 @@ export default function PageComposer() {
   const [selectedBlockId, setSelectedBlockId] = useState<string | null>(null);
   const [viewport, setViewport] = useState<ViewportKey>("desktop");
   const [showBlockPicker, setShowBlockPicker] = useState(false);
+  const [loaderPickerState, setLoaderPickerState] = useState<{
+    open: boolean;
+    propName: string | null;
+  }>({ open: false, propName: null });
   const saveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const iframeRef = useRef<HTMLIFrameElement>(null);
   const { send } = useEditorMessages(iframeRef);
@@ -231,6 +242,47 @@ export default function PageComposer() {
     setShowBlockPicker(false);
   };
 
+  // Handle binding a loader to a prop on the selected block
+  const handleBindLoader = (loaderRef: LoaderRef) => {
+    if (!selectedBlockId || !loaderPickerState.propName) return;
+
+    const propName = loaderPickerState.propName;
+    const updatedBlocks = blocks.map((block) =>
+      block.id === selectedBlockId
+        ? { ...block, props: { ...block.props, [propName]: loaderRef } }
+        : block,
+    );
+
+    pushBlocks(updatedBlocks);
+    send({
+      type: "deco:update-block",
+      blockId: selectedBlockId,
+      props: updatedBlocks.find((b) => b.id === selectedBlockId)!.props,
+    });
+    debouncedSave(updatedBlocks);
+    setLoaderPickerState({ open: false, propName: null });
+  };
+
+  // Handle removing a loader binding from a prop
+  const handleRemoveLoaderBinding = (propName: string) => {
+    if (!selectedBlockId) return;
+
+    const updatedBlocks = blocks.map((block) => {
+      if (block.id !== selectedBlockId) return block;
+      const newProps = { ...block.props };
+      delete newProps[propName];
+      return { ...block, props: newProps };
+    });
+
+    pushBlocks(updatedBlocks);
+    send({
+      type: "deco:update-block",
+      blockId: selectedBlockId,
+      props: updatedBlocks.find((b) => b.id === selectedBlockId)!.props,
+    });
+    debouncedSave(updatedBlocks);
+  };
+
   // Manual save (flush debounce)
   const handleSave = async () => {
     if (!localPage) return;
@@ -379,6 +431,62 @@ export default function PageComposer() {
                 formData={selectedBlock.props}
                 onChange={handlePropChange}
               />
+
+              {/* Loader bindings section */}
+              <div className="mt-4 pt-4 border-t border-border space-y-2">
+                <h4 className="text-xs font-medium text-muted-foreground uppercase tracking-wider">
+                  Loader Bindings
+                </h4>
+
+                {/* Show existing loader bindings */}
+                {Object.entries(selectedBlock.props)
+                  .filter(([, value]) => isLoaderRef(value))
+                  .map(([propName, value]) => {
+                    const ref = value as LoaderRef;
+                    return (
+                      <div
+                        key={propName}
+                        className="flex items-center justify-between text-xs bg-muted/30 rounded px-2 py-1.5"
+                      >
+                        <div className="min-w-0">
+                          <span className="font-medium">{propName}</span>
+                          <span className="text-muted-foreground ml-1">
+                            &larr; {ref.__loaderRef}
+                          </span>
+                        </div>
+                        <button
+                          type="button"
+                          onClick={() => handleRemoveLoaderBinding(propName)}
+                          className="text-destructive hover:text-destructive/80 shrink-0 ml-2"
+                        >
+                          Remove
+                        </button>
+                      </div>
+                    );
+                  })}
+
+                {/* Bind loader button for each schema prop */}
+                {Object.keys(
+                  (blockDef.schema as Record<string, unknown>)?.properties ??
+                    {},
+                )
+                  .filter(
+                    (propName) => !isLoaderRef(selectedBlock.props[propName]),
+                  )
+                  .map((propName) => (
+                    <button
+                      key={propName}
+                      type="button"
+                      onClick={() =>
+                        setLoaderPickerState({ open: true, propName })
+                      }
+                      className="flex items-center gap-1.5 text-xs text-muted-foreground hover:text-foreground transition-colors"
+                    >
+                      <span>Bind loader to</span>
+                      <span className="font-medium">{propName}</span>
+                    </button>
+                  ))}
+              </div>
             </div>
           ) : selectedBlockId ? (
             <div className="flex items-center justify-center h-full p-4">
@@ -402,6 +510,16 @@ export default function PageComposer() {
         onClose={() => setShowBlockPicker(false)}
         onSelect={handleAddBlock}
       />
+
+      {/* Loader picker modal */}
+      <LoaderPicker
+        open={loaderPickerState.open}
+        onOpenChange={(open) =>
+          setLoaderPickerState((prev) => ({ ...prev, open }))
+        }
+        onSelect={handleBindLoader}
+        propName={loaderPickerState.propName ?? ""}
+      />
     </div>
   );
 }
diff --git a/packages/mesh-plugin-site-editor/client/lib/page-api.ts b/packages/mesh-plugin-site-editor/client/lib/page-api.ts
index ef39cb05e9..ed081539b5 100644
--- a/packages/mesh-plugin-site-editor/client/lib/page-api.ts
+++ b/packages/mesh-plugin-site-editor/client/lib/page-api.ts
@@ -28,6 +28,25 @@ export interface BlockInstance {
   props: Record<string, unknown>;
 }
 
+/** Reference to a loader from a block instance prop value */
+export interface LoaderRef {
+  /** LoaderDefinition ID from .deco/loaders/ */
+  __loaderRef: string;
+  /** Optional: pick a specific field from loader output */
+  field?: string;
+  /** Configured input parameter values for this binding */
+  params?: Record<string, unknown>;
+}
+
+/** Check if a prop value is a loader reference */
+export function isLoaderRef(value: unknown): value is LoaderRef {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    "__loaderRef" in (value as Record<string, unknown>)
+  );
+}
+
 export interface Page {
   id: string;
   path: string;

From abad4377ad59b6728d7d727168f07aab123d5780 Mon Sep 17 00:00:00 2001
From: Guilherme Rodrigues <gui@deco.cx>
Date: Sat, 14 Feb 2026 11:26:18 -0300
Subject: [PATCH 20/26] feat(05-03): starter template with React 19, Vite 7,
 Tailwind 4, and example sections

- package.json with React 19, React Router 7, Vite 7, Tailwind CSS 4
- react-router.config.ts with prerender reading .deco/pages/
- Three example sections (hero, features, footer) with typed prop interfaces
- Products loader with typed input/output
- Home route and catch-all route rendering sections from page config
- Root layout with Tailwind CSS import and cn utility
---
 packages/starter-template/app/app.css         |   1 +
 .../app/components/sections/features.tsx      |  70 +++++++++++++++++
 .../app/components/sections/footer.tsx        |  43 +++++++++++
 .../app/components/sections/hero.tsx          |  51 ++++++++++++
 packages/starter-template/app/lib/utils.ts    |   4 +
 .../starter-template/app/loaders/products.ts  |  48 ++++++++++++
 packages/starter-template/app/root.tsx        |  24 ++++++
 packages/starter-template/app/routes.ts       |   6 ++
 packages/starter-template/app/routes/$.tsx    |  73 ++++++++++++++++++
 packages/starter-template/app/routes/home.tsx |  37 +++++++++
 packages/starter-template/package.json        |  26 +++++++
 packages/starter-template/public/favicon.ico  | Bin 0 -> 72 bytes
 .../starter-template/react-router.config.ts   |  28 +++++++
 packages/starter-template/tailwind.config.ts  |   5 ++
 packages/starter-template/tsconfig.json       |  23 ++++++
 packages/starter-template/vite.config.ts      |   7 ++
 16 files changed, 446 insertions(+)
 create mode 100644 packages/starter-template/app/app.css
 create mode 100644 packages/starter-template/app/components/sections/features.tsx
 create mode 100644 packages/starter-template/app/components/sections/footer.tsx
 create mode 100644 packages/starter-template/app/components/sections/hero.tsx
 create mode 100644 packages/starter-template/app/lib/utils.ts
 create mode 100644 packages/starter-template/app/loaders/products.ts
 create mode 100644 packages/starter-template/app/root.tsx
 create mode 100644 packages/starter-template/app/routes.ts
 create mode 100644 packages/starter-template/app/routes/$.tsx
 create mode 100644 packages/starter-template/app/routes/home.tsx
 create mode 100644 packages/starter-template/package.json
 create mode 100644 packages/starter-template/public/favicon.ico
 create mode 100644 packages/starter-template/react-router.config.ts
 create mode 100644 packages/starter-template/tailwind.config.ts
 create mode 100644 packages/starter-template/tsconfig.json
 create mode 100644 packages/starter-template/vite.config.ts

diff --git a/packages/starter-template/app/app.css b/packages/starter-template/app/app.css
new file mode 100644
index 0000000000..f1d8c73cdc
--- /dev/null
+++ b/packages/starter-template/app/app.css
@@ -0,0 +1 @@
+@import "tailwindcss";
diff --git a/packages/starter-template/app/components/sections/features.tsx b/packages/starter-template/app/components/sections/features.tsx
new file mode 100644
index 0000000000..9c5a14e2f6
--- /dev/null
+++ b/packages/starter-template/app/components/sections/features.tsx
@@ -0,0 +1,70 @@
+import { cn } from "../../lib/utils";
+
+export interface Feature {
+  /** Feature title */
+  title: string;
+  /** Feature description */
+  description: string;
+  /** Icon name (optional) */
+  icon?: string;
+}
+
+export interface FeaturesProps {
+  /** Section heading */
+  heading: string;
+  /** List of features to display */
+  features: Feature[];
+  /** Number of columns (2, 3, or 4) */
+  columns?: 2 | 3 | 4;
+}
+
+const iconMap: Record<string, string> = {
+  edit: "\u270F\uFE0F",
+  code: "\uD83D\uDCBB",
+  "git-branch": "\uD83D\uDD00",
+  star: "\u2B50",
+  rocket: "\uD83D\uDE80",
+  shield: "\uD83D\uDEE1\uFE0F",
+};
+
+const gridClasses: Record<number, string> = {
+  2: "grid grid-cols-1 gap-8 md:grid-cols-2",
+  3: "grid grid-cols-1 gap-8 md:grid-cols-3",
+  4: "grid grid-cols-1 gap-8 md:grid-cols-4",
+};
+
+export default function Features({
+  heading,
+  features,
+  columns = 3,
+}: FeaturesProps) {
+  return (
+    <section className="px-6 py-20">
+      <div className="mx-auto max-w-6xl">
+        <h2 className="mb-12 text-center text-3xl font-bold text-gray-900">
+          {heading}
+        </h2>
+        <div className={cn(gridClasses[columns] ?? gridClasses[3])}>
+          {features.map((feature) => (
+            <div
+              key={feature.title}
+              className="rounded-xl border border-gray-200 p-6 transition hover:shadow-lg"
+            >
+              {feature.icon && (
+                <div className="mb-4 text-3xl">
+                  {iconMap[feature.icon] ?? feature.icon}
+                </div>
+              )}
+              <h3 className="mb-2 text-xl font-semibold text-gray-900">
+                {feature.title}
+              </h3>
+              <p className="leading-relaxed text-gray-600">
+                {feature.description}
+              </p>
+            </div>
+          ))}
+        </div>
+      </div>
+    </section>
+  );
+}
diff --git a/packages/starter-template/app/components/sections/footer.tsx b/packages/starter-template/app/components/sections/footer.tsx
new file mode 100644
index 0000000000..0b8a4da2fb
--- /dev/null
+++ b/packages/starter-template/app/components/sections/footer.tsx
@@ -0,0 +1,43 @@
+export interface FooterLink {
+  /** Link display text */
+  label: string;
+  /** Link URL */
+  url: string;
+}
+
+export interface FooterProps {
+  /** Company or site name */
+  siteName: string;
+  /** Copyright year */
+  year?: number;
+  /** Navigation links */
+  links: FooterLink[];
+}
+
+export default function Footer({ siteName, year, links }: FooterProps) {
+  const displayYear = year ?? new Date().getFullYear();
+
+  return (
+    <footer className="bg-gray-900 px-6 py-12 text-gray-300">
+      <div className="mx-auto max-w-6xl">
+        <div className="flex flex-col items-center justify-between gap-6 md:flex-row">
+          <div className="text-lg font-semibold text-white">{siteName}</div>
+          <nav className="flex flex-wrap gap-6">
+            {links.map((link) => (
+              <a
+                key={link.url}
+                href={link.url}
+                className="transition hover:text-white"
+              >
+                {link.label}
+              </a>
+            ))}
+          </nav>
+        </div>
+        <div className="mt-8 border-t border-gray-800 pt-6 text-center text-sm text-gray-500">
+          &copy; {displayYear} {siteName}. All rights reserved.
+        </div>
+      </div>
+    </footer>
+  );
+}
diff --git a/packages/starter-template/app/components/sections/hero.tsx b/packages/starter-template/app/components/sections/hero.tsx
new file mode 100644
index 0000000000..e25bfd4438
--- /dev/null
+++ b/packages/starter-template/app/components/sections/hero.tsx
@@ -0,0 +1,51 @@
+export interface HeroProps {
+  /** Main headline text */
+  title: string;
+  /** Supporting description */
+  subtitle: string;
+  /** Call-to-action button text */
+  ctaText: string;
+  /** CTA button link URL */
+  ctaUrl: string;
+  /** Optional background image URL */
+  backgroundImage?: string;
+}
+
+export default function Hero({
+  title,
+  subtitle,
+  ctaText,
+  ctaUrl,
+  backgroundImage,
+}: HeroProps) {
+  return (
+    <section
+      className="relative flex min-h-[60vh] items-center justify-center bg-gradient-to-br from-blue-600 to-purple-700 px-6 py-24 text-center text-white"
+      style={
+        backgroundImage
+          ? {
+              backgroundImage: `url(${backgroundImage})`,
+              backgroundSize: "cover",
+              backgroundPosition: "center",
+            }
+          : undefined
+      }
+    >
+      {backgroundImage && (
+        <div className="absolute inset-0 bg-gradient-to-br from-blue-600/80 to-purple-700/80" />
+      )}
+      <div className="relative z-10 mx-auto max-w-3xl">
+        <h1 className="mb-6 text-4xl font-bold tracking-tight md:text-6xl">
+          {title}
+        </h1>
+        <p className="mb-8 text-lg text-white/90 md:text-xl">{subtitle}</p>
+        <a
+          href={ctaUrl}
+          className="inline-block rounded-lg bg-white px-8 py-3 font-semibold text-blue-700 shadow-lg transition hover:bg-gray-100"
+        >
+          {ctaText}
+        </a>
+      </div>
+    </section>
+  );
+}
diff --git a/packages/starter-template/app/lib/utils.ts b/packages/starter-template/app/lib/utils.ts
new file mode 100644
index 0000000000..772f190251
--- /dev/null
+++ b/packages/starter-template/app/lib/utils.ts
@@ -0,0 +1,4 @@
+/** Merge class names, filtering out falsy values */
+export function cn(...classes: (string | undefined | null | false)[]): string {
+  return classes.filter(Boolean).join(" ");
+}
diff --git a/packages/starter-template/app/loaders/products.ts b/packages/starter-template/app/loaders/products.ts
new file mode 100644
index 0000000000..84fa5ba0d2
--- /dev/null
+++ b/packages/starter-template/app/loaders/products.ts
@@ -0,0 +1,48 @@
+export interface ProductsInput {
+  /** Maximum number of products to return */
+  limit?: number;
+  /** Category filter */
+  category?: string;
+}
+
+export interface Product {
+  id: string;
+  name: string;
+  price: number;
+  image: string;
+}
+
+/** Fetches product data from an API */
+export default async function products(
+  input: ProductsInput,
+): Promise<Product[]> {
+  // Return mock data for the starter template
+  const allProducts: Product[] = [
+    {
+      id: "1",
+      name: "Classic T-Shirt",
+      price: 29.99,
+      image: "/images/tshirt.jpg",
+    },
+    {
+      id: "2",
+      name: "Denim Jacket",
+      price: 89.99,
+      image: "/images/jacket.jpg",
+    },
+    {
+      id: "3",
+      name: "Canvas Sneakers",
+      price: 59.99,
+      image: "/images/sneakers.jpg",
+    },
+  ];
+
+  const filtered = input.category
+    ? allProducts.filter((p) =>
+        p.name.toLowerCase().includes(input.category!.toLowerCase()),
+      )
+    : allProducts;
+
+  return filtered.slice(0, input.limit ?? 10);
+}
diff --git a/packages/starter-template/app/root.tsx b/packages/starter-template/app/root.tsx
new file mode 100644
index 0000000000..59dd1b4068
--- /dev/null
+++ b/packages/starter-template/app/root.tsx
@@ -0,0 +1,24 @@
+import { Links, Meta, Outlet, Scripts, ScrollRestoration } from "react-router";
+import "./app.css";
+
+export function Layout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <Meta />
+        <Links />
+      </head>
+      <body className="min-h-screen bg-white text-gray-900 antialiased">
+        {children}
+        <ScrollRestoration />
+        <Scripts />
+      </body>
+    </html>
+  );
+}
+
+export default function Root() {
+  return <Outlet />;
+}
diff --git a/packages/starter-template/app/routes.ts b/packages/starter-template/app/routes.ts
new file mode 100644
index 0000000000..be59ec410c
--- /dev/null
+++ b/packages/starter-template/app/routes.ts
@@ -0,0 +1,6 @@
+import { type RouteConfig, index, route } from "@react-router/dev/routes";
+
+export default [
+  index("routes/home.tsx"),
+  route("*", "routes/$.tsx"),
+] satisfies RouteConfig;
diff --git a/packages/starter-template/app/routes/$.tsx b/packages/starter-template/app/routes/$.tsx
new file mode 100644
index 0000000000..644781fdfc
--- /dev/null
+++ b/packages/starter-template/app/routes/$.tsx
@@ -0,0 +1,73 @@
+import { useParams } from "react-router";
+import Hero from "../components/sections/hero";
+import Features from "../components/sections/features";
+import Footer from "../components/sections/footer";
+
+const sectionRegistry: Record<string, React.ComponentType<any>> = {
+  "sections--Hero": Hero,
+  "sections--Features": Features,
+  "sections--Footer": Footer,
+};
+
+interface BlockInstance {
+  id: string;
+  blockType: string;
+  props: Record<string, unknown>;
+}
+
+interface PageConfig {
+  id: string;
+  path: string;
+  title: string;
+  blocks: BlockInstance[];
+  metadata?: {
+    description?: string;
+  };
+}
+
+// At build time (prerender), page configs are loaded from .deco/pages/.
+// This map is populated by the prerender data loading step.
+const pageCache = new Map<string, PageConfig>();
+
+// Eagerly load all page configs using Vite's import.meta.glob
+const pageModules = import.meta.glob<PageConfig>("../../.deco/pages/*.json", {
+  eager: true,
+  import: "default",
+});
+
+for (const [, config] of Object.entries(pageModules)) {
+  if (config?.path && !config.deleted) {
+    pageCache.set(config.path, config);
+  }
+}
+
+export default function CatchAllPage() {
+  const params = useParams();
+  const path = `/${params["*"] ?? ""}`;
+
+  const page = pageCache.get(path);
+
+  if (!page) {
+    return (
+      <main className="flex min-h-screen items-center justify-center">
+        <div className="text-center">
+          <h1 className="mb-4 text-4xl font-bold text-gray-900">404</h1>
+          <p className="text-gray-600">Page not found</p>
+        </div>
+      </main>
+    );
+  }
+
+  return (
+    <main>
+      {page.blocks.map((block) => {
+        const Section = sectionRegistry[block.blockType];
+        if (!Section) {
+          console.warn(`Unknown block type: ${block.blockType}`);
+          return null;
+        }
+        return <Section key={block.id} {...block.props} />;
+      })}
+    </main>
+  );
+}
diff --git a/packages/starter-template/app/routes/home.tsx b/packages/starter-template/app/routes/home.tsx
new file mode 100644
index 0000000000..3c261d85da
--- /dev/null
+++ b/packages/starter-template/app/routes/home.tsx
@@ -0,0 +1,37 @@
+import type { Route } from "./+types/home";
+import Hero from "../components/sections/hero";
+import Features from "../components/sections/features";
+import Footer from "../components/sections/footer";
+import pageConfig from "../../.deco/pages/page_home.json";
+
+const sectionRegistry: Record<string, React.ComponentType<any>> = {
+  "sections--Hero": Hero,
+  "sections--Features": Features,
+  "sections--Footer": Footer,
+};
+
+export function meta(_args: Route.MetaArgs) {
+  return [
+    { title: pageConfig.title ?? "Home" },
+    {
+      name: "description",
+      content:
+        pageConfig.metadata?.description ?? "Welcome to your deco.cx site",
+    },
+  ];
+}
+
+export default function Home() {
+  return (
+    <main>
+      {pageConfig.blocks.map((block) => {
+        const Section = sectionRegistry[block.blockType];
+        if (!Section) {
+          console.warn(`Unknown block type: ${block.blockType}`);
+          return null;
+        }
+        return <Section key={block.id} {...block.props} />;
+      })}
+    </main>
+  );
+}
diff --git a/packages/starter-template/package.json b/packages/starter-template/package.json
new file mode 100644
index 0000000000..3775703fb5
--- /dev/null
+++ b/packages/starter-template/package.json
@@ -0,0 +1,26 @@
+{
+  "name": "@decocms/starter-template",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "react-router dev",
+    "build": "react-router build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "react-router": "^7.6.3",
+    "@react-router/dev": "^7.6.3",
+    "@react-router/node": "^7.6.3"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.0.4",
+    "typescript": "^5.9.3",
+    "vite": "^7.2.1",
+    "tailwindcss": "^4.1.10",
+    "@tailwindcss/vite": "^4.1.10"
+  }
+}
diff --git a/packages/starter-template/public/favicon.ico b/packages/starter-template/public/favicon.ico
new file mode 100644
index 0000000000000000000000000000000000000000..115d361cf3a008099fc70968182cbc6380ac7a5f
GIT binary patch
literal 72
ucmZQzU<5%%1|TWHV8Fn@AO^%5KnxUOU;@(;K$3xh1x%t7|A7MkfdBwB^#!K@

literal 0
HcmV?d00001

diff --git a/packages/starter-template/react-router.config.ts b/packages/starter-template/react-router.config.ts
new file mode 100644
index 0000000000..d2faf60988
--- /dev/null
+++ b/packages/starter-template/react-router.config.ts
@@ -0,0 +1,28 @@
+import type { Config } from "@react-router/dev/config";
+import { readdir, readFile } from "fs/promises";
+import { join } from "path";
+
+export default {
+  ssr: false,
+  async prerender() {
+    const pagesDir = join(process.cwd(), ".deco/pages");
+    const staticPaths = ["/"];
+
+    try {
+      const files = await readdir(pagesDir);
+      const cmsPages = await Promise.all(
+        files
+          .filter((f) => f.endsWith(".json"))
+          .map(async (f) => {
+            const content = await readFile(join(pagesDir, f), "utf-8");
+            const page = JSON.parse(content);
+            if (page.deleted) return null;
+            return page.path;
+          }),
+      );
+      return [...staticPaths, ...cmsPages.filter(Boolean)];
+    } catch {
+      return staticPaths;
+    }
+  },
+} satisfies Config;
diff --git a/packages/starter-template/tailwind.config.ts b/packages/starter-template/tailwind.config.ts
new file mode 100644
index 0000000000..6f69fed101
--- /dev/null
+++ b/packages/starter-template/tailwind.config.ts
@@ -0,0 +1,5 @@
+import type { Config } from "tailwindcss";
+
+export default {
+  content: ["./app/**/*.{ts,tsx}"],
+} satisfies Config;
diff --git a/packages/starter-template/tsconfig.json b/packages/starter-template/tsconfig.json
new file mode 100644
index 0000000000..221d7370fa
--- /dev/null
+++ b/packages/starter-template/tsconfig.json
@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": ["vite/client"]
+  },
+  "include": [
+    "app/**/*.ts",
+    "app/**/*.tsx",
+    "vite.config.ts",
+    "react-router.config.ts"
+  ]
+}
diff --git a/packages/starter-template/vite.config.ts b/packages/starter-template/vite.config.ts
new file mode 100644
index 0000000000..8dd51ac72f
--- /dev/null
+++ b/packages/starter-template/vite.config.ts
@@ -0,0 +1,7 @@
+import { reactRouter } from "@react-router/dev/vite";
+import tailwindcss from "@tailwindcss/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [tailwindcss(), reactRouter()],
+});

From dc82ec15048bea421c6c94d4f1f382345a988c02 Mon Sep 17 00:00:00 2001
From: Guilherme Rodrigues <gui@deco.cx>
Date: Sat, 14 Feb 2026 11:26:30 -0300
Subject: [PATCH 21/26] feat(05-01): extend SITE_BINDING with branch tools and
 create branch API

- Add CREATE_BRANCH, LIST_BRANCHES, MERGE_BRANCH, DELETE_BRANCH to SITE_BINDING (optional)
- Create 4 server tools (CMS_BRANCH_LIST/CREATE/MERGE/DELETE)
- Create client branch-api.ts with graceful degradation
- Add DRAFT_BRANCH_PREFIX constant to shared.ts
- Add branches query key group

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/bindings/src/well-known/site.ts      | 128 +++++++++++++++++-
 .../client/lib/branch-api.ts                  |  95 +++++++++++++
 .../client/lib/query-keys.ts                  |   4 +
 .../server/tools/branch-create.ts             |  54 ++++++++
 .../server/tools/branch-delete.ts             |  48 +++++++
 .../server/tools/branch-list.ts               |  52 +++++++
 .../server/tools/branch-merge.ts              |  59 ++++++++
 .../server/tools/index.ts                     |   9 ++
 packages/mesh-plugin-site-editor/shared.ts    |   3 +
 9 files changed, 450 insertions(+), 2 deletions(-)
 create mode 100644 packages/mesh-plugin-site-editor/client/lib/branch-api.ts
 create mode 100644 packages/mesh-plugin-site-editor/server/tools/branch-create.ts
 create mode 100644 packages/mesh-plugin-site-editor/server/tools/branch-delete.ts
 create mode 100644 packages/mesh-plugin-site-editor/server/tools/branch-list.ts
 create mode 100644 packages/mesh-plugin-site-editor/server/tools/branch-merge.ts

diff --git a/packages/bindings/src/well-known/site.ts b/packages/bindings/src/well-known/site.ts
index 465a8c556c..9178a3fb90 100644
--- a/packages/bindings/src/well-known/site.ts
+++ b/packages/bindings/src/well-known/site.ts
@@ -1,7 +1,8 @@
 /**
  * Site Well-Known Binding
  *
- * Defines the interface for site file operations (read, write, list).
+ * Defines the interface for site file operations (read, write, list)
+ * and branch lifecycle operations (create, list, merge, delete).
  * Any MCP that implements this binding can provide file management
  * for a site's pages, sections, and loaders.
  *
@@ -9,6 +10,10 @@
  * - READ_FILE: Read a file's content by path
  * - PUT_FILE: Write content to a file by path
  * - LIST_FILES: List files with optional prefix filtering
+ * - CREATE_BRANCH: Create a new branch (optional)
+ * - LIST_BRANCHES: List all branches (optional)
+ * - MERGE_BRANCH: Merge a source branch into target (optional)
+ * - DELETE_BRANCH: Delete a branch (optional)
  */
 
 import { z } from "zod";
@@ -71,6 +76,83 @@ const ListFilesOutputSchema = z.object({
 export type ListFilesInput = z.infer<typeof ListFilesInputSchema>;
 export type ListFilesOutput = z.infer<typeof ListFilesOutputSchema>;
 
+// ============================================================================
+// Branch Tool Schemas (optional -- not all MCPs support branches)
+// ============================================================================
+
+/**
+ * CREATE_BRANCH - Create a new branch
+ */
+const CreateBranchInputSchema = z.object({
+  name: z.string().describe("Branch name to create"),
+  from: z
+    .string()
+    .optional()
+    .describe("Source branch to create from (defaults to 'main')"),
+});
+
+const CreateBranchOutputSchema = z.object({
+  success: z.boolean().describe("Whether the branch was created"),
+  branch: z.string().describe("Name of the created branch"),
+});
+
+export type CreateBranchInput = z.infer<typeof CreateBranchInputSchema>;
+export type CreateBranchOutput = z.infer<typeof CreateBranchOutputSchema>;
+
+/**
+ * LIST_BRANCHES - List all branches
+ */
+const ListBranchesInputSchema = z.object({});
+
+const ListBranchesOutputSchema = z.object({
+  branches: z.array(
+    z.object({
+      name: z.string().describe("Branch name"),
+      isDefault: z.boolean().describe("Whether this is the default branch"),
+    }),
+  ),
+});
+
+export type ListBranchesInput = z.infer<typeof ListBranchesInputSchema>;
+export type ListBranchesOutput = z.infer<typeof ListBranchesOutputSchema>;
+
+/**
+ * MERGE_BRANCH - Merge a source branch into a target branch
+ */
+const MergeBranchInputSchema = z.object({
+  source: z.string().describe("Source branch to merge from"),
+  target: z
+    .string()
+    .optional()
+    .describe("Target branch to merge into (defaults to 'main')"),
+  deleteSource: z
+    .boolean()
+    .optional()
+    .describe("Whether to delete the source branch after merge"),
+});
+
+const MergeBranchOutputSchema = z.object({
+  success: z.boolean().describe("Whether the merge succeeded"),
+  message: z.string().optional().describe("Additional merge details"),
+});
+
+export type MergeBranchInput = z.infer<typeof MergeBranchInputSchema>;
+export type MergeBranchOutput = z.infer<typeof MergeBranchOutputSchema>;
+
+/**
+ * DELETE_BRANCH - Delete a branch
+ */
+const DeleteBranchInputSchema = z.object({
+  name: z.string().describe("Branch name to delete"),
+});
+
+const DeleteBranchOutputSchema = z.object({
+  success: z.boolean().describe("Whether the branch was deleted"),
+});
+
+export type DeleteBranchInput = z.infer<typeof DeleteBranchInputSchema>;
+export type DeleteBranchOutput = z.infer<typeof DeleteBranchOutputSchema>;
+
 // ============================================================================
 // Binding Definition
 // ============================================================================
@@ -78,7 +160,7 @@ export type ListFilesOutput = z.infer<typeof ListFilesOutputSchema>;
 /**
  * Site Binding
  *
- * Defines the interface for site file operations.
+ * Defines the interface for site file operations and branch lifecycle.
  * Any MCP that implements this binding can be used with the Site Editor plugin
  * to provide a CMS UI for managing pages, sections, and loaders.
  *
@@ -86,6 +168,12 @@ export type ListFilesOutput = z.infer<typeof ListFilesOutputSchema>;
  * - READ_FILE: Read a file's content
  * - PUT_FILE: Write content to a file
  * - LIST_FILES: List files with prefix filtering
+ *
+ * Optional tools (branch lifecycle):
+ * - CREATE_BRANCH: Create a new branch
+ * - LIST_BRANCHES: List all branches
+ * - MERGE_BRANCH: Merge source branch into target
+ * - DELETE_BRANCH: Delete a branch
  */
 export const SITE_BINDING = [
   {
@@ -103,6 +191,42 @@ export const SITE_BINDING = [
     inputSchema: ListFilesInputSchema,
     outputSchema: ListFilesOutputSchema,
   } satisfies ToolBinder<"LIST_FILES", ListFilesInput, ListFilesOutput>,
+  {
+    name: "CREATE_BRANCH" as const,
+    inputSchema: CreateBranchInputSchema,
+    outputSchema: CreateBranchOutputSchema,
+    opt: true,
+  } satisfies ToolBinder<
+    "CREATE_BRANCH",
+    CreateBranchInput,
+    CreateBranchOutput
+  >,
+  {
+    name: "LIST_BRANCHES" as const,
+    inputSchema: ListBranchesInputSchema,
+    outputSchema: ListBranchesOutputSchema,
+    opt: true,
+  } satisfies ToolBinder<
+    "LIST_BRANCHES",
+    ListBranchesInput,
+    ListBranchesOutput
+  >,
+  {
+    name: "MERGE_BRANCH" as const,
+    inputSchema: MergeBranchInputSchema,
+    outputSchema: MergeBranchOutputSchema,
+    opt: true,
+  } satisfies ToolBinder<"MERGE_BRANCH", MergeBranchInput, MergeBranchOutput>,
+  {
+    name: "DELETE_BRANCH" as const,
+    inputSchema: DeleteBranchInputSchema,
+    outputSchema: DeleteBranchOutputSchema,
+    opt: true,
+  } satisfies ToolBinder<
+    "DELETE_BRANCH",
+    DeleteBranchInput,
+    DeleteBranchOutput
+  >,
 ] as const satisfies Binder;
 
 export type SiteBinding = typeof SITE_BINDING;
diff --git a/packages/mesh-plugin-site-editor/client/lib/branch-api.ts b/packages/mesh-plugin-site-editor/client/lib/branch-api.ts
new file mode 100644
index 0000000000..f2524a26f9
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/lib/branch-api.ts
@@ -0,0 +1,95 @@
+/**
+ * Branch API helpers
+ *
+ * Client-side branch lifecycle operations using SITE_BINDING tools
+ * (CREATE_BRANCH, LIST_BRANCHES, MERGE_BRANCH, DELETE_BRANCH).
+ * All functions gracefully degrade if branch tools are not supported by the MCP.
+ */
+
+import type { TypedToolCaller } from "@decocms/bindings";
+import type { SiteBinding } from "@decocms/bindings/site";
+import { DRAFT_BRANCH_PREFIX } from "../../shared";
+
+type ToolCaller = TypedToolCaller<SiteBinding>;
+
+export interface BranchInfo {
+  name: string;
+  isDefault: boolean;
+}
+
+/**
+ * List all branches for the site.
+ * Returns null if branch tools are not supported.
+ */
+export async function listBranches(
+  toolCaller: ToolCaller,
+): Promise<{ branches: BranchInfo[] } | null> {
+  try {
+    const result = await toolCaller("LIST_BRANCHES", {});
+    return { branches: result.branches };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Create a new draft branch.
+ * Automatically prepends the draft/ prefix to the name.
+ * Returns null if branch tools are not supported.
+ */
+export async function createBranch(
+  toolCaller: ToolCaller,
+  name: string,
+  from?: string,
+): Promise<{ success: boolean; branch: string } | null> {
+  try {
+    const branchName = name.startsWith(DRAFT_BRANCH_PREFIX)
+      ? name
+      : `${DRAFT_BRANCH_PREFIX}${name}`;
+    const result = await toolCaller("CREATE_BRANCH", {
+      name: branchName,
+      from,
+    });
+    return { success: result.success, branch: result.branch };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Merge a source branch into a target branch.
+ * Returns null if branch tools are not supported.
+ */
+export async function mergeBranch(
+  toolCaller: ToolCaller,
+  source: string,
+  target?: string,
+  deleteSource?: boolean,
+): Promise<{ success: boolean; message?: string } | null> {
+  try {
+    const result = await toolCaller("MERGE_BRANCH", {
+      source,
+      target,
+      deleteSource,
+    });
+    return { success: result.success, message: result.message };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Delete a branch.
+ * Returns null if branch tools are not supported.
+ */
+export async function deleteBranch(
+  toolCaller: ToolCaller,
+  name: string,
+): Promise<{ success: boolean } | null> {
+  try {
+    const result = await toolCaller("DELETE_BRANCH", { name });
+    return { success: result.success };
+  } catch {
+    return null;
+  }
+}
diff --git a/packages/mesh-plugin-site-editor/client/lib/query-keys.ts b/packages/mesh-plugin-site-editor/client/lib/query-keys.ts
index ab87173338..5a825d0655 100644
--- a/packages/mesh-plugin-site-editor/client/lib/query-keys.ts
+++ b/packages/mesh-plugin-site-editor/client/lib/query-keys.ts
@@ -21,6 +21,10 @@ export const queryKeys = {
     detail: (connectionId: string, loaderId: string) =>
       ["site-editor", "loaders", connectionId, loaderId] as const,
   },
+  branches: {
+    all: (connectionId: string) =>
+      ["site-editor", "branches", connectionId] as const,
+  },
 } as const;
 
 /** Shorthand for block query keys */
diff --git a/packages/mesh-plugin-site-editor/server/tools/branch-create.ts b/packages/mesh-plugin-site-editor/server/tools/branch-create.ts
new file mode 100644
index 0000000000..50cef5eb17
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/server/tools/branch-create.ts
@@ -0,0 +1,54 @@
+/**
+ * CMS_BRANCH_CREATE Tool
+ *
+ * Creates a new branch for the site via MCP branch operations.
+ */
+
+import { z } from "zod";
+import type { ServerPluginToolDefinition } from "@decocms/bindings/server-plugin";
+
+export const BRANCH_CREATE: ServerPluginToolDefinition = {
+  name: "CMS_BRANCH_CREATE",
+  description: "Create a new branch for the site.",
+  inputSchema: z.object({
+    connectionId: z.string().describe("MCP connection ID for the site"),
+    name: z.string().describe("Branch name to create"),
+    from: z
+      .string()
+      .optional()
+      .describe("Source branch to create from (defaults to 'main')"),
+  }),
+  outputSchema: z.object({
+    success: z.boolean(),
+    branch: z.string(),
+  }),
+
+  handler: async (input, ctx) => {
+    const { connectionId, name, from } = input as {
+      connectionId: string;
+      name: string;
+      from?: string;
+    };
+    const proxy = await ctx.createMCPProxy(connectionId);
+
+    try {
+      const result = await proxy.callTool({
+        name: "CREATE_BRANCH",
+        arguments: { name, from },
+      });
+
+      const content = result.content?.[0]?.text;
+      if (!content) {
+        return { success: false, branch: name };
+      }
+
+      try {
+        return JSON.parse(content);
+      } catch {
+        return { success: !result.isError, branch: name };
+      }
+    } finally {
+      await proxy.close?.();
+    }
+  },
+};
diff --git a/packages/mesh-plugin-site-editor/server/tools/branch-delete.ts b/packages/mesh-plugin-site-editor/server/tools/branch-delete.ts
new file mode 100644
index 0000000000..0cc5aa3107
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/server/tools/branch-delete.ts
@@ -0,0 +1,48 @@
+/**
+ * CMS_BRANCH_DELETE Tool
+ *
+ * Deletes a branch via MCP branch operations.
+ */
+
+import { z } from "zod";
+import type { ServerPluginToolDefinition } from "@decocms/bindings/server-plugin";
+
+export const BRANCH_DELETE: ServerPluginToolDefinition = {
+  name: "CMS_BRANCH_DELETE",
+  description: "Delete a branch.",
+  inputSchema: z.object({
+    connectionId: z.string().describe("MCP connection ID for the site"),
+    name: z.string().describe("Branch name to delete"),
+  }),
+  outputSchema: z.object({
+    success: z.boolean(),
+  }),
+
+  handler: async (input, ctx) => {
+    const { connectionId, name } = input as {
+      connectionId: string;
+      name: string;
+    };
+    const proxy = await ctx.createMCPProxy(connectionId);
+
+    try {
+      const result = await proxy.callTool({
+        name: "DELETE_BRANCH",
+        arguments: { name },
+      });
+
+      const content = result.content?.[0]?.text;
+      if (!content) {
+        return { success: !result.isError };
+      }
+
+      try {
+        return JSON.parse(content);
+      } catch {
+        return { success: !result.isError };
+      }
+    } finally {
+      await proxy.close?.();
+    }
+  },
+};
diff --git a/packages/mesh-plugin-site-editor/server/tools/branch-list.ts b/packages/mesh-plugin-site-editor/server/tools/branch-list.ts
new file mode 100644
index 0000000000..da51b2dd3a
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/server/tools/branch-list.ts
@@ -0,0 +1,52 @@
+/**
+ * CMS_BRANCH_LIST Tool
+ *
+ * Lists all branches for the site via MCP branch operations.
+ */
+
+import { z } from "zod";
+import type { ServerPluginToolDefinition } from "@decocms/bindings/server-plugin";
+
+export const BRANCH_LIST: ServerPluginToolDefinition = {
+  name: "CMS_BRANCH_LIST",
+  description: "List all branches for the site.",
+  inputSchema: z.object({
+    connectionId: z.string().describe("MCP connection ID for the site"),
+  }),
+  outputSchema: z.object({
+    branches: z.array(
+      z.object({
+        name: z.string(),
+        isDefault: z.boolean(),
+      }),
+    ),
+  }),
+
+  handler: async (input, ctx) => {
+    const { connectionId } = input as { connectionId: string };
+    const proxy = await ctx.createMCPProxy(connectionId);
+
+    try {
+      const result = await proxy.callTool({
+        name: "LIST_BRANCHES",
+        arguments: {},
+      });
+
+      const content = result.content?.[0]?.text;
+      if (!content) {
+        return { branches: [{ name: "main", isDefault: true }] };
+      }
+
+      try {
+        return JSON.parse(content);
+      } catch {
+        return { branches: [{ name: "main", isDefault: true }] };
+      }
+    } catch {
+      // Branch tools not supported, return default
+      return { branches: [{ name: "main", isDefault: true }] };
+    } finally {
+      await proxy.close?.();
+    }
+  },
+};
diff --git a/packages/mesh-plugin-site-editor/server/tools/branch-merge.ts b/packages/mesh-plugin-site-editor/server/tools/branch-merge.ts
new file mode 100644
index 0000000000..934e6bedac
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/server/tools/branch-merge.ts
@@ -0,0 +1,59 @@
+/**
+ * CMS_BRANCH_MERGE Tool
+ *
+ * Merges a source branch into a target branch via MCP branch operations.
+ */
+
+import { z } from "zod";
+import type { ServerPluginToolDefinition } from "@decocms/bindings/server-plugin";
+
+export const BRANCH_MERGE: ServerPluginToolDefinition = {
+  name: "CMS_BRANCH_MERGE",
+  description: "Merge a source branch into a target branch.",
+  inputSchema: z.object({
+    connectionId: z.string().describe("MCP connection ID for the site"),
+    source: z.string().describe("Source branch to merge from"),
+    target: z
+      .string()
+      .optional()
+      .describe("Target branch to merge into (defaults to 'main')"),
+    deleteSource: z
+      .boolean()
+      .optional()
+      .describe("Whether to delete the source branch after merge"),
+  }),
+  outputSchema: z.object({
+    success: z.boolean(),
+    message: z.string().optional(),
+  }),
+
+  handler: async (input, ctx) => {
+    const { connectionId, source, target, deleteSource } = input as {
+      connectionId: string;
+      source: string;
+      target?: string;
+      deleteSource?: boolean;
+    };
+    const proxy = await ctx.createMCPProxy(connectionId);
+
+    try {
+      const result = await proxy.callTool({
+        name: "MERGE_BRANCH",
+        arguments: { source, target, deleteSource },
+      });
+
+      const content = result.content?.[0]?.text;
+      if (!content) {
+        return { success: !result.isError };
+      }
+
+      try {
+        return JSON.parse(content);
+      } catch {
+        return { success: !result.isError, message: content };
+      }
+    } finally {
+      await proxy.close?.();
+    }
+  },
+};
diff --git a/packages/mesh-plugin-site-editor/server/tools/index.ts b/packages/mesh-plugin-site-editor/server/tools/index.ts
index 3337d5d0d6..a711b20602 100644
--- a/packages/mesh-plugin-site-editor/server/tools/index.ts
+++ b/packages/mesh-plugin-site-editor/server/tools/index.ts
@@ -4,6 +4,7 @@
  * Page CRUD tools for managing CMS pages stored in .deco/pages/.
  * Block scanner and management tools for .deco/blocks/.
  * Loader scanner and management tools for .deco/loaders/.
+ * Branch lifecycle tools for draft/publish workflow.
  */
 
 import type { ServerPluginToolDefinition } from "@decocms/bindings/server-plugin";
@@ -19,6 +20,10 @@ import { BLOCK_REGISTER } from "./block-register";
 import { LOADER_SCAN } from "./loader-scan";
 import { LOADER_LIST } from "./loader-list";
 import { LOADER_GET } from "./loader-get";
+import { BRANCH_LIST } from "./branch-list";
+import { BRANCH_CREATE } from "./branch-create";
+import { BRANCH_MERGE } from "./branch-merge";
+import { BRANCH_DELETE } from "./branch-delete";
 
 export const tools: ServerPluginToolDefinition[] = [
   PAGE_LIST,
@@ -33,4 +38,8 @@ export const tools: ServerPluginToolDefinition[] = [
   LOADER_SCAN,
   LOADER_LIST,
   LOADER_GET,
+  BRANCH_LIST,
+  BRANCH_CREATE,
+  BRANCH_MERGE,
+  BRANCH_DELETE,
 ];
diff --git a/packages/mesh-plugin-site-editor/shared.ts b/packages/mesh-plugin-site-editor/shared.ts
index b247d58259..763fe342c3 100644
--- a/packages/mesh-plugin-site-editor/shared.ts
+++ b/packages/mesh-plugin-site-editor/shared.ts
@@ -7,3 +7,6 @@
 export const PLUGIN_ID = "site-editor";
 export const PLUGIN_DESCRIPTION =
   "CMS for managing site pages, sections, and loaders";
+
+/** Prefix for draft branches. Draft branches follow: draft/{descriptive-name} */
+export const DRAFT_BRANCH_PREFIX = "draft/";

From 898142e4598cfb3115ef735082cf5d4aa26b5b13 Mon Sep 17 00:00:00 2001
From: Guilherme Rodrigues <gui@deco.cx>
Date: Sat, 14 Feb 2026 11:27:10 -0300
Subject: [PATCH 22/26] feat(05-03): .deco scaffolding with pre-configured
 pages, blocks, and loaders

- Home page config with Hero, Features, Footer block instances
- Block definitions with JSON Schema matching TypeScript prop interfaces
- Loader definition with input/output schemas
- README with quick start, project structure, and usage guide
---
 .../.deco/blocks/sections--Features.json      | 49 ++++++++++
 .../.deco/blocks/sections--Footer.json        | 40 ++++++++
 .../.deco/blocks/sections--Hero.json          | 35 +++++++
 .../.deco/loaders/loaders--products.json      | 36 +++++++
 .../.deco/pages/page_home.json                | 60 ++++++++++++
 packages/starter-template/README.md           | 95 +++++++++++++++++++
 6 files changed, 315 insertions(+)
 create mode 100644 packages/starter-template/.deco/blocks/sections--Features.json
 create mode 100644 packages/starter-template/.deco/blocks/sections--Footer.json
 create mode 100644 packages/starter-template/.deco/blocks/sections--Hero.json
 create mode 100644 packages/starter-template/.deco/loaders/loaders--products.json
 create mode 100644 packages/starter-template/.deco/pages/page_home.json
 create mode 100644 packages/starter-template/README.md

diff --git a/packages/starter-template/.deco/blocks/sections--Features.json b/packages/starter-template/.deco/blocks/sections--Features.json
new file mode 100644
index 0000000000..d7da6cde87
--- /dev/null
+++ b/packages/starter-template/.deco/blocks/sections--Features.json
@@ -0,0 +1,49 @@
+{
+  "id": "sections--Features",
+  "type": "section",
+  "title": "Features",
+  "description": "Grid of feature cards with icon, title, and description",
+  "category": "sections",
+  "filePath": "app/components/sections/features.tsx",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "heading": { "type": "string", "description": "Section heading" },
+      "features": {
+        "type": "array",
+        "description": "List of features to display",
+        "items": {
+          "type": "object",
+          "properties": {
+            "title": { "type": "string", "description": "Feature title" },
+            "description": {
+              "type": "string",
+              "description": "Feature description"
+            },
+            "icon": { "type": "string", "description": "Icon name (optional)" }
+          },
+          "required": ["title", "description"]
+        }
+      },
+      "columns": {
+        "type": "number",
+        "description": "Number of columns (2, 3, or 4)",
+        "enum": [2, 3, 4]
+      }
+    },
+    "required": ["heading", "features"]
+  },
+  "defaults": {
+    "heading": "Features",
+    "features": [
+      { "title": "Feature 1", "description": "Description of feature 1" },
+      { "title": "Feature 2", "description": "Description of feature 2" },
+      { "title": "Feature 3", "description": "Description of feature 3" }
+    ],
+    "columns": 3
+  },
+  "metadata": {
+    "customized": false,
+    "lastScanned": "2026-01-01T00:00:00.000Z"
+  }
+}
diff --git a/packages/starter-template/.deco/blocks/sections--Footer.json b/packages/starter-template/.deco/blocks/sections--Footer.json
new file mode 100644
index 0000000000..0b3102ba92
--- /dev/null
+++ b/packages/starter-template/.deco/blocks/sections--Footer.json
@@ -0,0 +1,40 @@
+{
+  "id": "sections--Footer",
+  "type": "section",
+  "title": "Footer",
+  "description": "Site footer with navigation links and copyright",
+  "category": "sections",
+  "filePath": "app/components/sections/footer.tsx",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "siteName": { "type": "string", "description": "Company or site name" },
+      "year": { "type": "number", "description": "Copyright year" },
+      "links": {
+        "type": "array",
+        "description": "Navigation links",
+        "items": {
+          "type": "object",
+          "properties": {
+            "label": { "type": "string", "description": "Link display text" },
+            "url": { "type": "string", "description": "Link URL" }
+          },
+          "required": ["label", "url"]
+        }
+      }
+    },
+    "required": ["siteName", "links"]
+  },
+  "defaults": {
+    "siteName": "My Site",
+    "year": 2026,
+    "links": [
+      { "label": "Home", "url": "/" },
+      { "label": "About", "url": "/about" }
+    ]
+  },
+  "metadata": {
+    "customized": false,
+    "lastScanned": "2026-01-01T00:00:00.000Z"
+  }
+}
diff --git a/packages/starter-template/.deco/blocks/sections--Hero.json b/packages/starter-template/.deco/blocks/sections--Hero.json
new file mode 100644
index 0000000000..9ee20ae72a
--- /dev/null
+++ b/packages/starter-template/.deco/blocks/sections--Hero.json
@@ -0,0 +1,35 @@
+{
+  "id": "sections--Hero",
+  "type": "section",
+  "title": "Hero",
+  "description": "Full-width hero section with headline, subtitle, and call-to-action",
+  "category": "sections",
+  "filePath": "app/components/sections/hero.tsx",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "title": { "type": "string", "description": "Main headline text" },
+      "subtitle": { "type": "string", "description": "Supporting description" },
+      "ctaText": {
+        "type": "string",
+        "description": "Call-to-action button text"
+      },
+      "ctaUrl": { "type": "string", "description": "CTA button link URL" },
+      "backgroundImage": {
+        "type": "string",
+        "description": "Optional background image URL"
+      }
+    },
+    "required": ["title", "subtitle", "ctaText", "ctaUrl"]
+  },
+  "defaults": {
+    "title": "Welcome",
+    "subtitle": "Your site, your way",
+    "ctaText": "Learn More",
+    "ctaUrl": "#"
+  },
+  "metadata": {
+    "customized": false,
+    "lastScanned": "2026-01-01T00:00:00.000Z"
+  }
+}
diff --git a/packages/starter-template/.deco/loaders/loaders--products.json b/packages/starter-template/.deco/loaders/loaders--products.json
new file mode 100644
index 0000000000..b8afd453f0
--- /dev/null
+++ b/packages/starter-template/.deco/loaders/loaders--products.json
@@ -0,0 +1,36 @@
+{
+  "id": "loaders--products",
+  "type": "loader",
+  "title": "Products",
+  "description": "Fetches product data from an API",
+  "category": "loaders",
+  "filePath": "app/loaders/products.ts",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "limit": {
+        "type": "number",
+        "description": "Maximum number of products to return"
+      },
+      "category": { "type": "string", "description": "Category filter" }
+    }
+  },
+  "outputSchema": {
+    "type": "array",
+    "items": {
+      "type": "object",
+      "properties": {
+        "id": { "type": "string" },
+        "name": { "type": "string" },
+        "price": { "type": "number" },
+        "image": { "type": "string" }
+      },
+      "required": ["id", "name", "price", "image"]
+    }
+  },
+  "defaults": { "limit": 10 },
+  "metadata": {
+    "customized": false,
+    "lastScanned": "2026-01-01T00:00:00.000Z"
+  }
+}
diff --git a/packages/starter-template/.deco/pages/page_home.json b/packages/starter-template/.deco/pages/page_home.json
new file mode 100644
index 0000000000..8740297a97
--- /dev/null
+++ b/packages/starter-template/.deco/pages/page_home.json
@@ -0,0 +1,60 @@
+{
+  "id": "page_home",
+  "path": "/",
+  "title": "Home",
+  "blocks": [
+    {
+      "id": "block_hero1",
+      "blockType": "sections--Hero",
+      "props": {
+        "title": "Build Beautiful Sites with deco.cx",
+        "subtitle": "A stack-agnostic CMS that works with your existing TypeScript codebase",
+        "ctaText": "Get Started",
+        "ctaUrl": "/docs"
+      }
+    },
+    {
+      "id": "block_feat1",
+      "blockType": "sections--Features",
+      "props": {
+        "heading": "Why deco.cx?",
+        "features": [
+          {
+            "title": "Visual Editing",
+            "description": "Edit your site visually with a live preview. Changes update in real-time.",
+            "icon": "edit"
+          },
+          {
+            "title": "TypeScript Native",
+            "description": "Your components define the CMS schema. No config files, no boilerplate.",
+            "icon": "code"
+          },
+          {
+            "title": "Git-Backed Content",
+            "description": "All content lives in git. Branch, review, and deploy with confidence.",
+            "icon": "git-branch"
+          }
+        ],
+        "columns": 3
+      }
+    },
+    {
+      "id": "block_foot1",
+      "blockType": "sections--Footer",
+      "props": {
+        "siteName": "My Site",
+        "year": 2026,
+        "links": [
+          { "label": "Home", "url": "/" },
+          { "label": "About", "url": "/about" },
+          { "label": "GitHub", "url": "https://github.com/deco-cx" }
+        ]
+      }
+    }
+  ],
+  "metadata": {
+    "description": "Default home page",
+    "createdAt": "2026-01-01T00:00:00.000Z",
+    "updatedAt": "2026-01-01T00:00:00.000Z"
+  }
+}
diff --git a/packages/starter-template/README.md b/packages/starter-template/README.md
new file mode 100644
index 0000000000..29443c8f44
--- /dev/null
+++ b/packages/starter-template/README.md
@@ -0,0 +1,95 @@
+# deco.cx Starter Template
+
+A starter template for building sites with deco.cx -- the stack-agnostic CMS for TypeScript.
+
+## Quick Start
+
+```bash
+npm install
+npm run dev
+```
+
+Open [http://localhost:5173](http://localhost:5173) to see your site.
+
+## Project Structure
+
+```
+app/
+  components/
+    sections/         # Page sections with typed props (CMS-editable)
+      hero.tsx        # Full-width hero with headline and CTA
+      features.tsx    # Feature grid with icons
+      footer.tsx      # Site footer with links
+  loaders/            # Data loaders (fetchers with typed input/output)
+    products.ts       # Example product loader
+  routes/             # React Router 7 page routes
+    home.tsx          # Home page (renders sections from .deco/pages/)
+    $.tsx             # Catch-all for CMS-managed pages
+  root.tsx            # Root layout
+.deco/
+  pages/              # Page compositions (which sections appear on which page)
+  blocks/             # Block definitions (JSON Schema for each section)
+  loaders/            # Loader definitions (input/output schemas)
+```
+
+## Adding a New Section
+
+1. Create a component in `app/components/sections/`:
+
+```tsx
+// app/components/sections/banner.tsx
+export interface BannerProps {
+  /** Banner message */
+  message: string;
+  /** Background color */
+  bgColor?: string;
+}
+
+export default function Banner({ message, bgColor = "#f0f0f0" }: BannerProps) {
+  return <div style={{ backgroundColor: bgColor }}>{message}</div>;
+}
+```
+
+2. Run the CMS scanner to generate the block definition in `.deco/blocks/`.
+
+3. Register the section in your route's `sectionRegistry`.
+
+## Adding a New Page
+
+Create a JSON file in `.deco/pages/`:
+
+```json
+{
+  "id": "page_about",
+  "path": "/about",
+  "title": "About",
+  "blocks": [
+    {
+      "id": "block_hero_about",
+      "blockType": "sections--Hero",
+      "props": {
+        "title": "About Us",
+        "subtitle": "Our story",
+        "ctaText": "Contact",
+        "ctaUrl": "/contact"
+      }
+    }
+  ]
+}
+```
+
+Pages are automatically discovered by the prerender config at build time.
+
+## Building for Production
+
+```bash
+npm run build
+```
+
+This prerenders all CMS pages as static HTML using React Router 7's prerender feature. The build reads `.deco/pages/` to discover all routes.
+
+## Learn More
+
+- [deco.cx Documentation](https://deco.cx/docs)
+- [React Router 7](https://reactrouter.com/)
+- [Tailwind CSS 4](https://tailwindcss.com/)

From a9ef28d1917c079d91b3ad57679d88f0dd5026f8 Mon Sep 17 00:00:00 2001
From: Guilherme Rodrigues <gui@deco.cx>
Date: Sat, 14 Feb 2026 11:28:51 -0300
Subject: [PATCH 23/26] feat(05-01): add branch switcher and publish bar UI
 components

- Create BranchSwitcher dropdown with draft creation inline form
- Create PublishBar with merge-to-main and discard actions
- Integrate both into plugin-header with lazy loading
- Use useSyncExternalStore-based branch store for cross-tree state

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../client/components/branch-switcher.tsx     | 159 ++++++++++++++++++
 .../client/components/plugin-header.tsx       |  21 ++-
 .../client/components/publish-bar.tsx         | 102 +++++++++++
 .../client/lib/branch-context.tsx             |  44 +++++
 4 files changed, 323 insertions(+), 3 deletions(-)
 create mode 100644 packages/mesh-plugin-site-editor/client/components/branch-switcher.tsx
 create mode 100644 packages/mesh-plugin-site-editor/client/components/publish-bar.tsx
 create mode 100644 packages/mesh-plugin-site-editor/client/lib/branch-context.tsx

diff --git a/packages/mesh-plugin-site-editor/client/components/branch-switcher.tsx b/packages/mesh-plugin-site-editor/client/components/branch-switcher.tsx
new file mode 100644
index 0000000000..b745db2dec
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/components/branch-switcher.tsx
@@ -0,0 +1,159 @@
+/**
+ * Branch Switcher Component
+ *
+ * Dropdown for switching between branches and creating new drafts.
+ * Uses module-level branch store to share the active branch across the plugin.
+ */
+
+import { useState, useRef } from "react";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { usePluginContext } from "@decocms/mesh-sdk/plugins";
+import { SITE_BINDING } from "@decocms/bindings/site";
+import { cn } from "@deco/ui/lib/utils.ts";
+import { ChevronDown, Loading01 } from "@untitledui/icons";
+import { listBranches, createBranch } from "../lib/branch-api";
+import { queryKeys } from "../lib/query-keys";
+import { useBranch } from "../lib/branch-context";
+import { DRAFT_BRANCH_PREFIX } from "../../shared";
+
+export default function BranchSwitcher() {
+  const { toolCaller, connectionId } = usePluginContext<typeof SITE_BINDING>();
+  const { currentBranch, setCurrentBranch } = useBranch();
+  const queryClient = useQueryClient();
+
+  const [isOpen, setIsOpen] = useState(false);
+  const [isCreating, setIsCreating] = useState(false);
+  const [draftName, setDraftName] = useState("");
+  const dropdownRef = useRef<HTMLDivElement>(null);
+
+  const { data: branchData } = useQuery({
+    queryKey: queryKeys.branches.all(connectionId),
+    queryFn: () => listBranches(toolCaller),
+  });
+
+  const createMutation = useMutation({
+    mutationFn: (name: string) => createBranch(toolCaller, name),
+    onSuccess: (result) => {
+      if (result?.success) {
+        setCurrentBranch(result.branch);
+        setIsCreating(false);
+        setDraftName("");
+        queryClient.invalidateQueries({
+          queryKey: queryKeys.branches.all(connectionId),
+        });
+      }
+    },
+  });
+
+  const branches = branchData?.branches ?? [{ name: "main", isDefault: true }];
+  const isDraft = currentBranch !== "main";
+
+  const handleBlur = (e: React.FocusEvent) => {
+    if (!dropdownRef.current?.contains(e.relatedTarget as Node)) {
+      setIsOpen(false);
+      setIsCreating(false);
+    }
+  };
+
+  const handleCreate = () => {
+    const trimmed = draftName.trim();
+    if (!trimmed) return;
+    createMutation.mutate(trimmed);
+  };
+
+  return (
+    <div className="relative" ref={dropdownRef} onBlur={handleBlur}>
+      <button
+        type="button"
+        onClick={() => setIsOpen(!isOpen)}
+        className="inline-flex items-center gap-1.5 px-2 py-1 text-xs font-medium rounded-md border border-border bg-background hover:bg-accent transition-colors"
+      >
+        <span
+          className={cn(
+            "size-2 rounded-full",
+            isDraft ? "bg-yellow-500" : "bg-green-500",
+          )}
+        />
+        <span className="max-w-32 truncate">{currentBranch}</span>
+        <ChevronDown size={12} />
+      </button>
+
+      {isOpen && (
+        <div className="absolute left-0 top-full mt-1 z-50 min-w-56 rounded-md border border-border bg-popover p-1 shadow-md">
+          {branches.map((branch) => (
+            <button
+              key={branch.name}
+              type="button"
+              onClick={() => {
+                setCurrentBranch(branch.name);
+                setIsOpen(false);
+              }}
+              className={cn(
+                "flex items-center gap-2 w-full px-2 py-1.5 text-xs rounded-sm hover:bg-accent transition-colors",
+                branch.name === currentBranch && "bg-accent",
+              )}
+            >
+              <span
+                className={cn(
+                  "size-2 rounded-full",
+                  branch.isDefault ? "bg-green-500" : "bg-yellow-500",
+                )}
+              />
+              <span className="flex-1 text-left truncate">{branch.name}</span>
+              {branch.isDefault && (
+                <span className="text-muted-foreground text-[10px]">
+                  published
+                </span>
+              )}
+            </button>
+          ))}
+
+          <div className="border-t border-border mt-1 pt-1">
+            {isCreating ? (
+              <div className="flex items-center gap-1 px-2 py-1">
+                <span className="text-xs text-muted-foreground">
+                  {DRAFT_BRANCH_PREFIX}
+                </span>
+                <input
+                  type="text"
+                  value={draftName}
+                  onChange={(e) => setDraftName(e.target.value)}
+                  onKeyDown={(e) => {
+                    if (e.key === "Enter") handleCreate();
+                    if (e.key === "Escape") {
+                      setIsCreating(false);
+                      setDraftName("");
+                    }
+                  }}
+                  placeholder="draft-name"
+                  className="flex-1 min-w-0 px-1 py-0.5 text-xs border border-border rounded bg-background focus:outline-none focus:ring-1 focus:ring-ring"
+                  autoFocus
+                />
+                <button
+                  type="button"
+                  onClick={handleCreate}
+                  disabled={createMutation.isPending || !draftName.trim()}
+                  className="px-2 py-0.5 text-xs font-medium rounded bg-primary text-primary-foreground hover:bg-primary/90 disabled:opacity-50 transition-colors"
+                >
+                  {createMutation.isPending ? (
+                    <Loading01 size={12} className="animate-spin" />
+                  ) : (
+                    "Create"
+                  )}
+                </button>
+              </div>
+            ) : (
+              <button
+                type="button"
+                onClick={() => setIsCreating(true)}
+                className="flex items-center gap-2 w-full px-2 py-1.5 text-xs text-muted-foreground hover:text-foreground hover:bg-accent rounded-sm transition-colors"
+              >
+                + New Draft
+              </button>
+            )}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/packages/mesh-plugin-site-editor/client/components/plugin-header.tsx b/packages/mesh-plugin-site-editor/client/components/plugin-header.tsx
index 4e139a30d6..9cf93fd3d6 100644
--- a/packages/mesh-plugin-site-editor/client/components/plugin-header.tsx
+++ b/packages/mesh-plugin-site-editor/client/components/plugin-header.tsx
@@ -1,13 +1,16 @@
 /**
  * Plugin Header Component
  *
- * Connection selector for the site editor plugin.
+ * Connection selector and branch switcher for the site editor plugin.
  * Uses native HTML elements to avoid type conflicts with UI package.
  */
 
 import type { PluginRenderHeaderProps } from "@decocms/bindings/plugins";
 import { File06, ChevronDown, Check } from "@untitledui/icons";
-import { useState, useRef } from "react";
+import { useState, useRef, lazy, Suspense } from "react";
+
+const BranchSwitcher = lazy(() => import("./branch-switcher"));
+const PublishBar = lazy(() => import("./publish-bar"));
 
 /**
  * Simple dropdown menu using native elements.
@@ -98,5 +101,17 @@ function ConnectionSelector({
 }
 
 export default function PluginHeader(props: PluginRenderHeaderProps) {
-  return <ConnectionSelector {...props} />;
+  return (
+    <div className="flex flex-col w-full">
+      <div className="flex items-center gap-3">
+        <ConnectionSelector {...props} />
+        <Suspense fallback={null}>
+          <BranchSwitcher />
+        </Suspense>
+      </div>
+      <Suspense fallback={null}>
+        <PublishBar />
+      </Suspense>
+    </div>
+  );
 }
diff --git a/packages/mesh-plugin-site-editor/client/components/publish-bar.tsx b/packages/mesh-plugin-site-editor/client/components/publish-bar.tsx
new file mode 100644
index 0000000000..86908b2c93
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/components/publish-bar.tsx
@@ -0,0 +1,102 @@
+/**
+ * Publish Bar Component
+ *
+ * Shown when the user is on a draft branch.
+ * Provides Publish (merge to main) and Discard (delete branch) actions.
+ */
+
+import { useState } from "react";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { usePluginContext } from "@decocms/mesh-sdk/plugins";
+import { SITE_BINDING } from "@decocms/bindings/site";
+import { cn } from "@deco/ui/lib/utils.ts";
+import { Loading01 } from "@untitledui/icons";
+import { mergeBranch, deleteBranch } from "../lib/branch-api";
+import { queryKeys } from "../lib/query-keys";
+import { useBranch } from "../lib/branch-context";
+
+export default function PublishBar() {
+  const { toolCaller, connectionId } = usePluginContext<typeof SITE_BINDING>();
+  const { currentBranch, setCurrentBranch } = useBranch();
+  const queryClient = useQueryClient();
+  const [showSuccess, setShowSuccess] = useState(false);
+
+  const publishMutation = useMutation({
+    mutationFn: () => mergeBranch(toolCaller, currentBranch, "main", true),
+    onSuccess: (result) => {
+      if (result?.success) {
+        setShowSuccess(true);
+        setCurrentBranch("main");
+        queryClient.invalidateQueries({
+          queryKey: queryKeys.branches.all(connectionId),
+        });
+        // Brief success flash
+        setTimeout(() => setShowSuccess(false), 2000);
+      }
+    },
+  });
+
+  const discardMutation = useMutation({
+    mutationFn: () => deleteBranch(toolCaller, currentBranch),
+    onSuccess: () => {
+      setCurrentBranch("main");
+      queryClient.invalidateQueries({
+        queryKey: queryKeys.branches.all(connectionId),
+      });
+    },
+  });
+
+  if (currentBranch === "main") return null;
+
+  if (showSuccess) {
+    return (
+      <div className="flex items-center justify-center gap-2 px-4 py-2 bg-green-50 border-b border-green-200 text-green-800 text-xs font-medium">
+        Published successfully
+      </div>
+    );
+  }
+
+  const isLoading = publishMutation.isPending || discardMutation.isPending;
+
+  return (
+    <div className="flex items-center gap-3 px-4 py-2 bg-amber-50 border-b border-amber-200">
+      <span className="flex-1 text-xs text-amber-800 font-medium truncate">
+        Draft: {currentBranch}
+      </span>
+
+      <button
+        type="button"
+        onClick={() => discardMutation.mutate()}
+        disabled={isLoading}
+        className={cn(
+          "px-3 py-1 text-xs font-medium rounded-md border transition-colors",
+          "border-red-300 text-red-700 hover:bg-red-50",
+          "disabled:opacity-50 disabled:cursor-not-allowed",
+        )}
+      >
+        {discardMutation.isPending ? (
+          <Loading01 size={12} className="animate-spin" />
+        ) : (
+          "Discard"
+        )}
+      </button>
+
+      <button
+        type="button"
+        onClick={() => publishMutation.mutate()}
+        disabled={isLoading}
+        className={cn(
+          "px-3 py-1 text-xs font-medium rounded-md transition-colors",
+          "bg-green-600 text-white hover:bg-green-700",
+          "disabled:opacity-50 disabled:cursor-not-allowed",
+        )}
+      >
+        {publishMutation.isPending ? (
+          <Loading01 size={12} className="animate-spin" />
+        ) : (
+          "Publish"
+        )}
+      </button>
+    </div>
+  );
+}
diff --git a/packages/mesh-plugin-site-editor/client/lib/branch-context.tsx b/packages/mesh-plugin-site-editor/client/lib/branch-context.tsx
new file mode 100644
index 0000000000..98df8e3093
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/lib/branch-context.tsx
@@ -0,0 +1,44 @@
+/**
+ * Branch Store
+ *
+ * Module-level store for the current branch state.
+ * Uses useSyncExternalStore so header and route components can share
+ * branch state without needing a common provider ancestor.
+ */
+
+import { useSyncExternalStore } from "react";
+
+type Listener = () => void;
+
+let currentBranch = "main";
+const listeners = new Set<Listener>();
+
+function subscribe(listener: Listener): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+function getSnapshot(): string {
+  return currentBranch;
+}
+
+function setCurrentBranch(branch: string): void {
+  if (branch === currentBranch) return;
+  currentBranch = branch;
+  for (const listener of listeners) {
+    listener();
+  }
+}
+
+/**
+ * Hook to access the current branch and setter.
+ * Works across any component in the site-editor plugin tree
+ * without requiring a shared context provider.
+ */
+export function useBranch(): {
+  currentBranch: string;
+  setCurrentBranch: (branch: string) => void;
+} {
+  const branch = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  return { currentBranch: branch, setCurrentBranch };
+}

From 9a74804bca68c8ba256e3b28e857f5a8e4939f61 Mon Sep 17 00:00:00 2001
From: Guilherme Rodrigues <gui@deco.cx>
Date: Sat, 14 Feb 2026 11:33:14 -0300
Subject: [PATCH 24/26] feat(05-02): extend SITE_BINDING with history tools and
 create server/client APIs

- Add GET_FILE_HISTORY and READ_FILE_AT optional tool binders to SITE_BINDING (9 total)
- Create CMS_FILE_HISTORY and CMS_FILE_READ_AT server tools in page-history.ts
- Create client history-api.ts with getFileHistory, readFileAt, revertPage
- Add history query key group to query-keys.ts
- Revert implemented as read-old-content + PUT_FILE (non-destructive)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/bindings/src/well-known/site.ts      |  67 +++++++++++
 .../client/lib/history-api.ts                 | 102 ++++++++++++++++
 .../client/lib/query-keys.ts                  |   4 +
 .../server/tools/index.ts                     |   3 +
 .../server/tools/page-history.ts              | 112 ++++++++++++++++++
 5 files changed, 288 insertions(+)
 create mode 100644 packages/mesh-plugin-site-editor/client/lib/history-api.ts
 create mode 100644 packages/mesh-plugin-site-editor/server/tools/page-history.ts

diff --git a/packages/bindings/src/well-known/site.ts b/packages/bindings/src/well-known/site.ts
index 9178a3fb90..b026049ab6 100644
--- a/packages/bindings/src/well-known/site.ts
+++ b/packages/bindings/src/well-known/site.ts
@@ -14,6 +14,8 @@
  * - LIST_BRANCHES: List all branches (optional)
  * - MERGE_BRANCH: Merge a source branch into target (optional)
  * - DELETE_BRANCH: Delete a branch (optional)
+ * - GET_FILE_HISTORY: Get commit history for a file (optional)
+ * - READ_FILE_AT: Read a file at a specific commit (optional)
  */
 
 import { z } from "zod";
@@ -153,6 +155,51 @@ const DeleteBranchOutputSchema = z.object({
 export type DeleteBranchInput = z.infer<typeof DeleteBranchInputSchema>;
 export type DeleteBranchOutput = z.infer<typeof DeleteBranchOutputSchema>;
 
+// ============================================================================
+// History Tool Schemas (optional -- not all MCPs support file history)
+// ============================================================================
+
+/**
+ * GET_FILE_HISTORY - Get commit history for a file
+ */
+const GetFileHistoryInputSchema = z.object({
+  path: z.string().describe("File path relative to project root"),
+  branch: z.string().optional().describe("Branch name (defaults to current)"),
+  limit: z
+    .number()
+    .optional()
+    .describe("Max entries to return (defaults to 50)"),
+});
+
+const GetFileHistoryOutputSchema = z.object({
+  entries: z.array(
+    z.object({
+      commitHash: z.string().describe("Git commit SHA"),
+      timestamp: z.number().describe("Commit timestamp (epoch ms)"),
+      author: z.string().describe("Commit author name"),
+      message: z.string().describe("Commit message"),
+    }),
+  ),
+});
+
+export type GetFileHistoryInput = z.infer<typeof GetFileHistoryInputSchema>;
+export type GetFileHistoryOutput = z.infer<typeof GetFileHistoryOutputSchema>;
+
+/**
+ * READ_FILE_AT - Read a file's content at a specific commit
+ */
+const ReadFileAtInputSchema = z.object({
+  path: z.string().describe("File path relative to project root"),
+  commitHash: z.string().describe("Git commit SHA to read from"),
+});
+
+const ReadFileAtOutputSchema = z.object({
+  content: z.string().describe("File content at the specified commit"),
+});
+
+export type ReadFileAtInput = z.infer<typeof ReadFileAtInputSchema>;
+export type ReadFileAtOutput = z.infer<typeof ReadFileAtOutputSchema>;
+
 // ============================================================================
 // Binding Definition
 // ============================================================================
@@ -174,6 +221,10 @@ export type DeleteBranchOutput = z.infer<typeof DeleteBranchOutputSchema>;
  * - LIST_BRANCHES: List all branches
  * - MERGE_BRANCH: Merge source branch into target
  * - DELETE_BRANCH: Delete a branch
+ *
+ * Optional tools (file history):
+ * - GET_FILE_HISTORY: Get commit history for a file
+ * - READ_FILE_AT: Read a file at a specific commit
  */
 export const SITE_BINDING = [
   {
@@ -227,6 +278,22 @@ export const SITE_BINDING = [
     DeleteBranchInput,
     DeleteBranchOutput
   >,
+  {
+    name: "GET_FILE_HISTORY" as const,
+    inputSchema: GetFileHistoryInputSchema,
+    outputSchema: GetFileHistoryOutputSchema,
+    opt: true,
+  } satisfies ToolBinder<
+    "GET_FILE_HISTORY",
+    GetFileHistoryInput,
+    GetFileHistoryOutput
+  >,
+  {
+    name: "READ_FILE_AT" as const,
+    inputSchema: ReadFileAtInputSchema,
+    outputSchema: ReadFileAtOutputSchema,
+    opt: true,
+  } satisfies ToolBinder<"READ_FILE_AT", ReadFileAtInput, ReadFileAtOutput>,
 ] as const satisfies Binder;
 
 export type SiteBinding = typeof SITE_BINDING;
diff --git a/packages/mesh-plugin-site-editor/client/lib/history-api.ts b/packages/mesh-plugin-site-editor/client/lib/history-api.ts
new file mode 100644
index 0000000000..aec2cc8cc7
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/lib/history-api.ts
@@ -0,0 +1,102 @@
+/**
+ * History API helpers
+ *
+ * Client-side file history operations using SITE_BINDING tools
+ * (GET_FILE_HISTORY, READ_FILE_AT). Revert is implemented as a
+ * read-old-content + write-as-new-version pattern using PUT_FILE.
+ * All functions gracefully degrade if history tools are not supported.
+ */
+
+import type { TypedToolCaller } from "@decocms/bindings";
+import type { SiteBinding } from "@decocms/bindings/site";
+
+type ToolCaller = TypedToolCaller<SiteBinding>;
+
+export interface HistoryEntry {
+  commitHash: string;
+  timestamp: number;
+  author: string;
+  message: string;
+}
+
+const PAGES_PREFIX = ".deco/pages/";
+
+/**
+ * Get the commit history for a file.
+ * Returns null if history tools are not supported.
+ */
+export async function getFileHistory(
+  toolCaller: ToolCaller,
+  path: string,
+  opts?: { branch?: string; limit?: number },
+): Promise<HistoryEntry[] | null> {
+  try {
+    const result = await toolCaller("GET_FILE_HISTORY", {
+      path,
+      branch: opts?.branch,
+      limit: opts?.limit,
+    });
+    return result.entries;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read a file's content at a specific commit.
+ * Returns null if history tools are not supported.
+ */
+export async function readFileAt(
+  toolCaller: ToolCaller,
+  path: string,
+  commitHash: string,
+): Promise<string | null> {
+  try {
+    const result = await toolCaller("READ_FILE_AT", { path, commitHash });
+    return result.content;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Revert a page to a previous version.
+ *
+ * Implements the "revert as PUT_FILE" pattern:
+ * 1. Read old content at the given commit hash
+ * 2. Parse JSON, update metadata.updatedAt to now
+ * 3. Write as new version via PUT_FILE
+ *
+ * This is non-destructive: old versions are preserved and revert
+ * creates a new commit.
+ */
+export async function revertPage(
+  toolCaller: ToolCaller,
+  pageId: string,
+  commitHash: string,
+): Promise<boolean> {
+  try {
+    const path = `${PAGES_PREFIX}${pageId}.json`;
+
+    // 1. Read old content
+    const oldContent = await readFileAt(toolCaller, path, commitHash);
+    if (!oldContent) return false;
+
+    // 2. Parse and update timestamp
+    const page = JSON.parse(oldContent);
+    page.metadata = {
+      ...page.metadata,
+      updatedAt: new Date().toISOString(),
+    };
+
+    // 3. Write as new version
+    await toolCaller("PUT_FILE", {
+      path,
+      content: JSON.stringify(page, null, 2),
+    });
+
+    return true;
+  } catch {
+    return false;
+  }
+}
diff --git a/packages/mesh-plugin-site-editor/client/lib/query-keys.ts b/packages/mesh-plugin-site-editor/client/lib/query-keys.ts
index 5a825d0655..79ae2a813a 100644
--- a/packages/mesh-plugin-site-editor/client/lib/query-keys.ts
+++ b/packages/mesh-plugin-site-editor/client/lib/query-keys.ts
@@ -25,6 +25,10 @@ export const queryKeys = {
     all: (connectionId: string) =>
       ["site-editor", "branches", connectionId] as const,
   },
+  history: {
+    page: (connectionId: string, pageId: string) =>
+      ["site-editor", "history", connectionId, pageId] as const,
+  },
 } as const;
 
 /** Shorthand for block query keys */
diff --git a/packages/mesh-plugin-site-editor/server/tools/index.ts b/packages/mesh-plugin-site-editor/server/tools/index.ts
index a711b20602..85f9077964 100644
--- a/packages/mesh-plugin-site-editor/server/tools/index.ts
+++ b/packages/mesh-plugin-site-editor/server/tools/index.ts
@@ -24,6 +24,7 @@ import { BRANCH_LIST } from "./branch-list";
 import { BRANCH_CREATE } from "./branch-create";
 import { BRANCH_MERGE } from "./branch-merge";
 import { BRANCH_DELETE } from "./branch-delete";
+import { FILE_HISTORY, FILE_READ_AT } from "./page-history";
 
 export const tools: ServerPluginToolDefinition[] = [
   PAGE_LIST,
@@ -42,4 +43,6 @@ export const tools: ServerPluginToolDefinition[] = [
   BRANCH_CREATE,
   BRANCH_MERGE,
   BRANCH_DELETE,
+  FILE_HISTORY,
+  FILE_READ_AT,
 ];
diff --git a/packages/mesh-plugin-site-editor/server/tools/page-history.ts b/packages/mesh-plugin-site-editor/server/tools/page-history.ts
new file mode 100644
index 0000000000..99803ae906
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/server/tools/page-history.ts
@@ -0,0 +1,112 @@
+/**
+ * CMS File History Tools
+ *
+ * Server tools for retrieving file history and reading files at specific commits.
+ * Proxies to GET_FILE_HISTORY and READ_FILE_AT via MCP.
+ */
+
+import { z } from "zod";
+import type { ServerPluginToolDefinition } from "@decocms/bindings/server-plugin";
+
+export const FILE_HISTORY: ServerPluginToolDefinition = {
+  name: "CMS_FILE_HISTORY",
+  description:
+    "Get the commit history for a CMS file, showing who changed it and when.",
+  inputSchema: z.object({
+    connectionId: z.string().describe("MCP connection ID for the site"),
+    path: z.string().describe("File path relative to project root"),
+    branch: z.string().optional().describe("Branch name (defaults to current)"),
+    limit: z
+      .number()
+      .optional()
+      .describe("Max entries to return (defaults to 50)"),
+  }),
+  outputSchema: z.object({
+    entries: z.array(
+      z.object({
+        commitHash: z.string(),
+        timestamp: z.number(),
+        author: z.string(),
+        message: z.string(),
+      }),
+    ),
+  }),
+
+  handler: async (input, ctx) => {
+    const { connectionId, path, branch, limit } = input as {
+      connectionId: string;
+      path: string;
+      branch?: string;
+      limit?: number;
+    };
+    const proxy = await ctx.createMCPProxy(connectionId);
+
+    try {
+      const result = await proxy.callTool({
+        name: "GET_FILE_HISTORY",
+        arguments: { path, branch, limit },
+      });
+
+      const content = result.content?.[0]?.text;
+      if (!content) {
+        return { entries: [] };
+      }
+
+      try {
+        return JSON.parse(content);
+      } catch {
+        return { entries: [] };
+      }
+    } catch {
+      // History tools not supported by this MCP
+      return { entries: [] };
+    } finally {
+      await proxy.close?.();
+    }
+  },
+};
+
+export const FILE_READ_AT: ServerPluginToolDefinition = {
+  name: "CMS_FILE_READ_AT",
+  description: "Read a CMS file's content at a specific commit hash.",
+  inputSchema: z.object({
+    connectionId: z.string().describe("MCP connection ID for the site"),
+    path: z.string().describe("File path relative to project root"),
+    commitHash: z.string().describe("Git commit SHA to read from"),
+  }),
+  outputSchema: z.object({
+    content: z.string(),
+  }),
+
+  handler: async (input, ctx) => {
+    const { connectionId, path, commitHash } = input as {
+      connectionId: string;
+      path: string;
+      commitHash: string;
+    };
+    const proxy = await ctx.createMCPProxy(connectionId);
+
+    try {
+      const result = await proxy.callTool({
+        name: "READ_FILE_AT",
+        arguments: { path, commitHash },
+      });
+
+      const content = result.content?.[0]?.text;
+      if (!content) {
+        return { content: "" };
+      }
+
+      try {
+        return JSON.parse(content);
+      } catch {
+        // If the response is plain text (not JSON-wrapped), return it directly
+        return { content };
+      }
+    } catch {
+      return { content: "" };
+    } finally {
+      await proxy.close?.();
+    }
+  },
+};

From d1d3823379824e78de75ea6fee0f25c6608443af Mon Sep 17 00:00:00 2001
From: Guilherme Rodrigues <gui@deco.cx>
Date: Sat, 14 Feb 2026 11:35:46 -0300
Subject: [PATCH 25/26] feat(05-02): add page history panel with diff view and
 revert integration

- Create PageHistory component with vertical timeline, relative timestamps, inline revert confirmation
- Create PageDiff component with structured property-level comparison (scalar fields + block changes)
- Add Clock icon button to page composer toolbar toggling history panel in right sidebar
- History panel shows author, message, view-diff, and one-click revert per version
- Diff view uses green/red backgrounds for added/removed blocks and prop changes

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../client/components/page-composer.tsx       |  17 +-
 .../client/components/page-diff.tsx           | 270 ++++++++++++++++++
 .../client/components/page-history.tsx        | 209 ++++++++++++++
 .../client/lib/query-keys.ts                  |   9 +
 4 files changed, 503 insertions(+), 2 deletions(-)
 create mode 100644 packages/mesh-plugin-site-editor/client/components/page-diff.tsx
 create mode 100644 packages/mesh-plugin-site-editor/client/components/page-history.tsx

diff --git a/packages/mesh-plugin-site-editor/client/components/page-composer.tsx b/packages/mesh-plugin-site-editor/client/components/page-composer.tsx
index d9f9780644..bd35081fa7 100644
--- a/packages/mesh-plugin-site-editor/client/components/page-composer.tsx
+++ b/packages/mesh-plugin-site-editor/client/components/page-composer.tsx
@@ -24,6 +24,7 @@ import {
   AlertCircle,
   ReverseLeft,
   ReverseRight,
+  Clock,
 } from "@untitledui/icons";
 import { toast } from "sonner";
 import { queryKeys } from "../lib/query-keys";
@@ -44,6 +45,7 @@ import { PropEditor } from "./prop-editor";
 import { SectionListSidebar } from "./section-list-sidebar";
 import { BlockPicker } from "./block-picker";
 import { LoaderPicker } from "./loader-picker";
+import PageHistory from "./page-history";
 
 export default function PageComposer() {
   const { toolCaller, connectionId } = usePluginContext<typeof SITE_BINDING>();
@@ -58,6 +60,7 @@ export default function PageComposer() {
     open: boolean;
     propName: string | null;
   }>({ open: false, propName: null });
+  const [showHistory, setShowHistory] = useState(false);
   const saveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const iframeRef = useRef<HTMLIFrameElement>(null);
   const { send } = useEditorMessages(iframeRef);
@@ -386,6 +389,14 @@ export default function PageComposer() {
             </Button>
           </div>
           <ViewportToggle value={viewport} onChange={setViewport} />
+          <Button
+            variant={showHistory ? "secondary" : "ghost"}
+            size="icon"
+            onClick={() => setShowHistory((prev) => !prev)}
+            title="Version History"
+          >
+            <Clock size={16} />
+          </Button>
           <Button size="sm" onClick={handleSave}>
             <Save01 size={14} className="mr-1" />
             Save
@@ -418,9 +429,11 @@ export default function PageComposer() {
           />
         </div>
 
-        {/* Right panel: prop editor */}
+        {/* Right panel: prop editor or history */}
         <div className="w-[320px] border-l border-border overflow-y-auto">
-          {selectedBlock && blockDef?.schema ? (
+          {showHistory ? (
+            <PageHistory pageId={pageId} />
+          ) : selectedBlock && blockDef?.schema ? (
             <div className="p-4">
               <h3 className="text-sm font-medium mb-3">
                 {blockDef.label ??
diff --git a/packages/mesh-plugin-site-editor/client/components/page-diff.tsx b/packages/mesh-plugin-site-editor/client/components/page-diff.tsx
new file mode 100644
index 0000000000..aaea2ae182
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/components/page-diff.tsx
@@ -0,0 +1,270 @@
+/**
+ * Page Diff Component
+ *
+ * Shows a readable diff between a historical version and the current page.
+ * Compares scalar fields (title, path) and block-level changes (added, removed, modified).
+ * Uses structured comparison rather than raw JSON diff.
+ */
+
+import { SITE_BINDING } from "@decocms/bindings/site";
+import { usePluginContext } from "@decocms/mesh-sdk/plugins";
+import { useQuery } from "@tanstack/react-query";
+import { Loading01 } from "@untitledui/icons";
+import { cn } from "@deco/ui/lib/utils.ts";
+import { queryKeys } from "../lib/query-keys";
+import { getPage, type Page, type BlockInstance } from "../lib/page-api";
+import { readFileAt } from "../lib/history-api";
+
+interface ScalarChange {
+  field: string;
+  oldValue: string;
+  newValue: string;
+}
+
+interface BlockChange {
+  type: "added" | "removed" | "modified";
+  blockId: string;
+  blockType: string;
+  propChanges?: Array<{
+    key: string;
+    oldValue: string;
+    newValue: string;
+  }>;
+}
+
+interface PageDiffResult {
+  scalarChanges: ScalarChange[];
+  blockChanges: BlockChange[];
+}
+
+function truncateValue(value: unknown, maxLen = 60): string {
+  const str =
+    typeof value === "string" ? value : (JSON.stringify(value) ?? "undefined");
+  return str.length > maxLen ? `${str.slice(0, maxLen)}...` : str;
+}
+
+/**
+ * Compute a property-level diff between two page versions.
+ */
+function diffPages(oldPage: Page, newPage: Page): PageDiffResult {
+  const scalarChanges: ScalarChange[] = [];
+  const blockChanges: BlockChange[] = [];
+
+  // Compare scalar fields
+  if (oldPage.title !== newPage.title) {
+    scalarChanges.push({
+      field: "title",
+      oldValue: oldPage.title,
+      newValue: newPage.title,
+    });
+  }
+  if (oldPage.path !== newPage.path) {
+    scalarChanges.push({
+      field: "path",
+      oldValue: oldPage.path,
+      newValue: newPage.path,
+    });
+  }
+
+  // Compare blocks by ID
+  const oldBlockMap = new Map(oldPage.blocks.map((b) => [b.id, b]));
+  const newBlockMap = new Map(newPage.blocks.map((b) => [b.id, b]));
+
+  // Find removed blocks
+  for (const [id, block] of oldBlockMap) {
+    if (!newBlockMap.has(id)) {
+      blockChanges.push({
+        type: "removed",
+        blockId: id,
+        blockType: block.blockType,
+      });
+    }
+  }
+
+  // Find added blocks
+  for (const [id, block] of newBlockMap) {
+    if (!oldBlockMap.has(id)) {
+      blockChanges.push({
+        type: "added",
+        blockId: id,
+        blockType: block.blockType,
+      });
+    }
+  }
+
+  // Find modified blocks
+  for (const [id, newBlock] of newBlockMap) {
+    const oldBlock = oldBlockMap.get(id);
+    if (!oldBlock) continue;
+
+    const propChanges = diffBlockProps(oldBlock, newBlock);
+    if (propChanges.length > 0) {
+      blockChanges.push({
+        type: "modified",
+        blockId: id,
+        blockType: newBlock.blockType,
+        propChanges,
+      });
+    }
+  }
+
+  return { scalarChanges, blockChanges };
+}
+
+/**
+ * Shallow comparison of block props, returning changed keys.
+ */
+function diffBlockProps(
+  oldBlock: BlockInstance,
+  newBlock: BlockInstance,
+): Array<{ key: string; oldValue: string; newValue: string }> {
+  const changes: Array<{ key: string; oldValue: string; newValue: string }> =
+    [];
+  const allKeys = new Set([
+    ...Object.keys(oldBlock.props),
+    ...Object.keys(newBlock.props),
+  ]);
+
+  for (const key of allKeys) {
+    const oldVal = oldBlock.props[key];
+    const newVal = newBlock.props[key];
+
+    if (JSON.stringify(oldVal) !== JSON.stringify(newVal)) {
+      changes.push({
+        key,
+        oldValue: truncateValue(oldVal),
+        newValue: truncateValue(newVal),
+      });
+    }
+  }
+
+  return changes;
+}
+
+interface PageDiffProps {
+  pageId: string;
+  commitHash: string;
+}
+
+export default function PageDiff({ pageId, commitHash }: PageDiffProps) {
+  const { toolCaller, connectionId } = usePluginContext<typeof SITE_BINDING>();
+
+  const path = `.deco/pages/${pageId}.json`;
+
+  // Fetch old version at commit
+  const { data: oldContent, isLoading: isLoadingOld } = useQuery({
+    queryKey: queryKeys.history.diff(connectionId, pageId, commitHash),
+    queryFn: () => readFileAt(toolCaller, path, commitHash),
+  });
+
+  // Fetch current version
+  const { data: currentPage, isLoading: isLoadingCurrent } = useQuery({
+    queryKey: queryKeys.pages.detail(connectionId, pageId),
+    queryFn: () => getPage(toolCaller, pageId),
+  });
+
+  if (isLoadingOld || isLoadingCurrent) {
+    return (
+      <div className="flex items-center gap-2 p-3 text-xs text-muted-foreground">
+        <Loading01 size={14} className="animate-spin" />
+        Loading diff...
+      </div>
+    );
+  }
+
+  if (!oldContent || !currentPage) {
+    return (
+      <p className="text-xs text-muted-foreground p-3">
+        Could not load version for comparison.
+      </p>
+    );
+  }
+
+  let oldPage: Page;
+  try {
+    oldPage = JSON.parse(oldContent);
+  } catch {
+    return (
+      <p className="text-xs text-muted-foreground p-3">
+        Could not parse historical version.
+      </p>
+    );
+  }
+
+  const diff = diffPages(oldPage, currentPage);
+
+  if (diff.scalarChanges.length === 0 && diff.blockChanges.length === 0) {
+    return (
+      <p className="text-xs text-muted-foreground p-3 bg-muted/30 rounded">
+        No differences found.
+      </p>
+    );
+  }
+
+  return (
+    <div className="space-y-2 text-xs">
+      {/* Scalar changes */}
+      {diff.scalarChanges.map((change) => (
+        <div key={change.field} className="rounded border border-border p-2">
+          <span className="font-medium">{change.field}</span>
+          <div className="mt-1 space-y-0.5">
+            <div className="bg-red-50 text-red-800 px-1.5 py-0.5 rounded font-mono">
+              - {change.oldValue}
+            </div>
+            <div className="bg-green-50 text-green-800 px-1.5 py-0.5 rounded font-mono">
+              + {change.newValue}
+            </div>
+          </div>
+        </div>
+      ))}
+
+      {/* Block changes */}
+      {diff.blockChanges.map((change) => (
+        <div
+          key={change.blockId}
+          className={cn(
+            "rounded border p-2",
+            change.type === "added" && "border-green-200 bg-green-50/50",
+            change.type === "removed" && "border-red-200 bg-red-50/50",
+            change.type === "modified" && "border-border",
+          )}
+        >
+          <div className="flex items-center gap-1.5">
+            <span
+              className={cn(
+                "inline-block px-1 py-0.5 rounded text-[10px] font-medium uppercase",
+                change.type === "added" && "bg-green-100 text-green-700",
+                change.type === "removed" && "bg-red-100 text-red-700",
+                change.type === "modified" && "bg-yellow-100 text-yellow-700",
+              )}
+            >
+              {change.type}
+            </span>
+            <span className="font-mono text-muted-foreground">
+              {change.blockType.replace("sections--", "")}
+            </span>
+          </div>
+
+          {/* Modified block prop changes */}
+          {change.propChanges && change.propChanges.length > 0 && (
+            <div className="mt-1.5 space-y-1 pl-2 border-l-2 border-yellow-200">
+              {change.propChanges.map((pc) => (
+                <div key={pc.key}>
+                  <span className="font-medium">{pc.key}:</span>
+                  <div className="mt-0.5 space-y-0.5">
+                    <div className="bg-red-50 text-red-800 px-1.5 py-0.5 rounded font-mono truncate">
+                      - {pc.oldValue}
+                    </div>
+                    <div className="bg-green-50 text-green-800 px-1.5 py-0.5 rounded font-mono truncate">
+                      + {pc.newValue}
+                    </div>
+                  </div>
+                </div>
+              ))}
+            </div>
+          )}
+        </div>
+      ))}
+    </div>
+  );
+}
diff --git a/packages/mesh-plugin-site-editor/client/components/page-history.tsx b/packages/mesh-plugin-site-editor/client/components/page-history.tsx
new file mode 100644
index 0000000000..8769100704
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/client/components/page-history.tsx
@@ -0,0 +1,209 @@
+/**
+ * Page History Panel
+ *
+ * Vertical timeline showing version history for a page.
+ * Each entry displays timestamp, author, message, and actions (view diff, revert).
+ * Revert creates a new version (non-destructive).
+ */
+
+import { useState } from "react";
+import { SITE_BINDING } from "@decocms/bindings/site";
+import { usePluginContext } from "@decocms/mesh-sdk/plugins";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { Loading01, RefreshCcw01, AlertCircle } from "@untitledui/icons";
+import { toast } from "sonner";
+import { queryKeys } from "../lib/query-keys";
+import {
+  getFileHistory,
+  revertPage,
+  type HistoryEntry,
+} from "../lib/history-api";
+import PageDiff from "./page-diff";
+
+/**
+ * Format a timestamp as a relative time string (e.g., "2 hours ago", "Yesterday").
+ */
+function formatRelativeTime(timestamp: number): string {
+  const now = Date.now();
+  const diff = now - timestamp;
+
+  const seconds = Math.floor(diff / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+  const days = Math.floor(hours / 24);
+
+  if (seconds < 60) return "Just now";
+  if (minutes < 60) return `${minutes}m ago`;
+  if (hours < 24) return `${hours}h ago`;
+  if (days === 1) return "Yesterday";
+  if (days < 30) return `${days}d ago`;
+
+  return new Date(timestamp).toLocaleDateString();
+}
+
+interface PageHistoryProps {
+  pageId: string;
+}
+
+export default function PageHistory({ pageId }: PageHistoryProps) {
+  const { toolCaller, connectionId } = usePluginContext<typeof SITE_BINDING>();
+  const queryClient = useQueryClient();
+
+  const [selectedEntry, setSelectedEntry] = useState<string | null>(null);
+  const [revertingHash, setRevertingHash] = useState<string | null>(null);
+  const [confirmingHash, setConfirmingHash] = useState<string | null>(null);
+
+  const {
+    data: entries,
+    isLoading,
+    error,
+  } = useQuery({
+    queryKey: queryKeys.history.page(connectionId, pageId),
+    queryFn: () =>
+      getFileHistory(toolCaller, `.deco/pages/${pageId}.json`, { limit: 50 }),
+  });
+
+  const handleRevert = async (entry: HistoryEntry) => {
+    setRevertingHash(entry.commitHash);
+    try {
+      const success = await revertPage(toolCaller, pageId, entry.commitHash);
+      if (success) {
+        toast.success("Page reverted successfully");
+        // Invalidate both page detail and history queries
+        queryClient.invalidateQueries({
+          queryKey: queryKeys.pages.detail(connectionId, pageId),
+        });
+        queryClient.invalidateQueries({
+          queryKey: queryKeys.history.page(connectionId, pageId),
+        });
+      } else {
+        toast.error("Failed to revert page");
+      }
+    } catch {
+      toast.error("Failed to revert page");
+    } finally {
+      setRevertingHash(null);
+      setConfirmingHash(null);
+    }
+  };
+
+  if (isLoading) {
+    return (
+      <div className="flex flex-col items-center justify-center p-8">
+        <Loading01
+          size={24}
+          className="animate-spin text-muted-foreground mb-2"
+        />
+        <p className="text-xs text-muted-foreground">Loading history...</p>
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className="flex flex-col items-center justify-center p-8">
+        <AlertCircle size={24} className="text-destructive mb-2" />
+        <p className="text-xs text-muted-foreground">Failed to load history</p>
+      </div>
+    );
+  }
+
+  if (!entries || entries.length === 0) {
+    return (
+      <div className="flex flex-col items-center justify-center p-8">
+        <p className="text-sm text-muted-foreground">
+          No version history available
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <div className="p-4">
+      <h3 className="text-sm font-medium mb-4">Version History</h3>
+
+      {/* Vertical timeline */}
+      <div className="relative border-l-2 border-gray-200 ml-2 space-y-0">
+        {entries.map((entry) => {
+          const isSelected = selectedEntry === entry.commitHash;
+          const isConfirming = confirmingHash === entry.commitHash;
+          const isReverting = revertingHash === entry.commitHash;
+
+          return (
+            <div key={entry.commitHash} className="relative pl-5 pb-4">
+              {/* Timeline dot */}
+              <div className="absolute -left-[5px] top-1.5 h-2 w-2 rounded-full bg-gray-400 border-2 border-white" />
+
+              {/* Entry content */}
+              <div className="space-y-1">
+                <div className="flex items-center gap-2 text-xs text-muted-foreground">
+                  <span>{formatRelativeTime(entry.timestamp)}</span>
+                  <span className="text-gray-300">|</span>
+                  <span className="truncate max-w-[120px]">{entry.author}</span>
+                </div>
+
+                <p className="text-xs leading-relaxed">
+                  {entry.message.length > 60
+                    ? `${entry.message.slice(0, 60)}...`
+                    : entry.message}
+                </p>
+
+                {/* Action buttons */}
+                <div className="flex items-center gap-1.5 pt-1">
+                  <button
+                    type="button"
+                    onClick={() =>
+                      setSelectedEntry(isSelected ? null : entry.commitHash)
+                    }
+                    className="text-xs text-blue-600 hover:text-blue-800 transition-colors"
+                  >
+                    {isSelected ? "Hide diff" : "View diff"}
+                  </button>
+
+                  {isConfirming ? (
+                    <span className="flex items-center gap-1 text-xs">
+                      <span className="text-muted-foreground">
+                        Are you sure?
+                      </span>
+                      <button
+                        type="button"
+                        onClick={() => handleRevert(entry)}
+                        disabled={isReverting}
+                        className="text-orange-600 hover:text-orange-800 font-medium transition-colors"
+                      >
+                        {isReverting ? "Reverting..." : "Revert"}
+                      </button>
+                      <button
+                        type="button"
+                        onClick={() => setConfirmingHash(null)}
+                        className="text-muted-foreground hover:text-foreground transition-colors"
+                      >
+                        Cancel
+                      </button>
+                    </span>
+                  ) : (
+                    <button
+                      type="button"
+                      onClick={() => setConfirmingHash(entry.commitHash)}
+                      className="flex items-center gap-0.5 text-xs text-orange-600 hover:text-orange-800 transition-colors"
+                    >
+                      <RefreshCcw01 size={10} />
+                      Revert
+                    </button>
+                  )}
+                </div>
+
+                {/* Inline diff view */}
+                {isSelected && (
+                  <div className="mt-2">
+                    <PageDiff pageId={pageId} commitHash={entry.commitHash} />
+                  </div>
+                )}
+              </div>
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
diff --git a/packages/mesh-plugin-site-editor/client/lib/query-keys.ts b/packages/mesh-plugin-site-editor/client/lib/query-keys.ts
index 79ae2a813a..eec46738fb 100644
--- a/packages/mesh-plugin-site-editor/client/lib/query-keys.ts
+++ b/packages/mesh-plugin-site-editor/client/lib/query-keys.ts
@@ -28,6 +28,15 @@ export const queryKeys = {
   history: {
     page: (connectionId: string, pageId: string) =>
       ["site-editor", "history", connectionId, pageId] as const,
+    diff: (connectionId: string, pageId: string, commitHash: string) =>
+      [
+        "site-editor",
+        "history",
+        connectionId,
+        pageId,
+        "diff",
+        commitHash,
+      ] as const,
   },
 } as const;
 

From e36e3431a929dc957e36e78163134302cb305558 Mon Sep 17 00:00:00 2001
From: Guilherme Rodrigues <gui@deco.cx>
Date: Sat, 14 Feb 2026 23:08:20 -0300
Subject: [PATCH 26/26] feat: site-editor routing, filesystem path resolution,
 and preview connect

- Per-plugin static routes to fix collision between site-editor and object-storage
- Root directory discovery via list_allowed_directories for correct path resolution
- Plugin router strips ID-only layout route prefix from URLs
- Preview panel with inline URL input form to connect dev server
- Preview URL persisted in connection metadata via COLLECTION_CONNECTIONS_UPDATE

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 apps/mesh/package.json                        |   1 +
 apps/mesh/src/tools/index.ts                  |   4 +
 apps/mesh/src/tools/registry.ts               |  13 +-
 .../src/web/components/binding-selector.tsx   | 177 ++++++++++---
 .../settings-tab/mcp-configuration-form.tsx   | 150 ++++++++++-
 apps/mesh/src/web/index.tsx                   |  39 ++-
 .../src/web/layouts/dynamic-plugin-layout.tsx |  17 +-
 apps/mesh/src/web/layouts/plugin-layout.tsx   | 232 +++++++++++++-----
 apps/mesh/src/web/routes/orgs/connections.tsx |  61 ++++-
 packages/bindings/src/core/binder.ts          |  51 +++-
 packages/bindings/src/core/plugin-router.tsx  |  44 +++-
 packages/bindings/src/index.ts                |   1 +
 packages/bindings/src/well-known/site.ts      |   3 +
 .../components/file-browser.tsx               |  11 +-
 .../mesh-plugin-object-storage/lib/router.ts  |  13 +-
 .../client/components/block-detail.tsx        |   9 +-
 .../client/components/loader-detail.tsx       |   9 +-
 .../client/components/loaders-list.tsx        |   2 +-
 .../client/components/page-composer.tsx       |  11 +-
 .../client/components/page-editor.tsx         |   2 +-
 .../client/components/pages-list.tsx          |   4 +-
 .../client/components/plugin-empty-state.tsx  | 167 ++++++++++++-
 .../client/components/preview-panel.tsx       |  60 ++++-
 .../client/components/sections-list.tsx       |   2 +-
 .../client/lib/router.ts                      |  41 +++-
 .../client/lib/use-tunnel-url.ts              |  64 +++--
 packages/mesh-plugin-site-editor/package.json |   1 +
 .../server/site-proxy.ts                      | 184 ++++++++++++++
 .../server/tools/block-get.ts                 |   3 +-
 .../server/tools/block-list.ts                |   3 +-
 .../server/tools/block-register.ts            |   3 +-
 .../server/tools/block-scan.ts                |   3 +-
 .../server/tools/loader-get.ts                |   3 +-
 .../server/tools/loader-list.ts               |   3 +-
 .../server/tools/loader-scan.ts               |   3 +-
 .../server/tools/page-create.ts               |   3 +-
 .../server/tools/page-delete.ts               |   3 +-
 .../server/tools/page-get.ts                  |   3 +-
 .../server/tools/page-list.ts                 |   3 +-
 .../server/tools/page-update.ts               |   3 +-
 packages/starter-template/package.json        |   3 +-
 41 files changed, 1195 insertions(+), 217 deletions(-)
 create mode 100644 packages/mesh-plugin-site-editor/server/site-proxy.ts

diff --git a/apps/mesh/package.json b/apps/mesh/package.json
index e1ae22155c..3db6a2c5a0 100644
--- a/apps/mesh/package.json
+++ b/apps/mesh/package.json
@@ -112,6 +112,7 @@
     "marked": "^15.0.6",
     "mesh-plugin-object-storage": "workspace:*",
     "mesh-plugin-private-registry": "workspace:*",
+    "mesh-plugin-site-editor": "workspace:*",
     "mesh-plugin-user-sandbox": "workspace:*",
     "mesh-plugin-reports": "workspace:*",
     "mesh-plugin-workflows": "workspace:*",
diff --git a/apps/mesh/src/tools/index.ts b/apps/mesh/src/tools/index.ts
index 777c902a37..334fd96d72 100644
--- a/apps/mesh/src/tools/index.ts
+++ b/apps/mesh/src/tools/index.ts
@@ -28,6 +28,7 @@ import * as OrganizationTools from "./organization";
 import * as ProjectTools from "./projects";
 import * as TagTools from "./tags";
 import * as ThreadTools from "./thread";
+import * as FilesystemTools from "./filesystem";
 import * as UserTools from "./user";
 import { ToolName } from "./registry";
 
@@ -128,6 +129,9 @@ const CORE_TOOLS = [
   ProjectTools.PROJECT_DELETE,
   ProjectTools.PROJECT_PLUGIN_CONFIG_GET,
   ProjectTools.PROJECT_PLUGIN_CONFIG_UPDATE,
+
+  // Filesystem tools
+  FilesystemTools.FILESYSTEM_PICK_DIRECTORY,
 ] as const satisfies { name: ToolName }[];
 
 // Plugin tools - collected at startup, gated by org settings at runtime
diff --git a/apps/mesh/src/tools/registry.ts b/apps/mesh/src/tools/registry.ts
index f237ccff94..3b6398f0c8 100644
--- a/apps/mesh/src/tools/registry.ts
+++ b/apps/mesh/src/tools/registry.ts
@@ -30,7 +30,8 @@ export type ToolCategory =
   | "Event Bus"
   | "Code Execution"
   | "Tags"
-  | "Projects";
+  | "Projects"
+  | "Filesystem";
 
 /**
  * All tool names - keep in sync with ALL_TOOLS in index.ts
@@ -120,6 +121,8 @@ const ALL_TOOL_NAMES = [
   "PROJECT_DELETE",
   "PROJECT_PLUGIN_CONFIG_GET",
   "PROJECT_PLUGIN_CONFIG_UPDATE",
+  // Filesystem tools
+  "FILESYSTEM_PICK_DIRECTORY",
 ] as const;
 
 /**
@@ -535,6 +538,12 @@ export const MANAGEMENT_TOOLS: ToolMetadata[] = [
     description: "Update project plugin configuration",
     category: "Projects",
   },
+  // Filesystem tools
+  {
+    name: "FILESYSTEM_PICK_DIRECTORY",
+    description: "Open native folder picker dialog",
+    category: "Filesystem",
+  },
 ];
 
 /**
@@ -612,6 +621,7 @@ const TOOL_LABELS: Record<ToolName, string> = {
   PROJECT_DELETE: "Delete project",
   PROJECT_PLUGIN_CONFIG_GET: "View plugin config",
   PROJECT_PLUGIN_CONFIG_UPDATE: "Update plugin config",
+  FILESYSTEM_PICK_DIRECTORY: "Pick directory",
 };
 
 // ============================================================================
@@ -635,6 +645,7 @@ export function getToolsByCategory() {
     "Code Execution": [],
     Tags: [],
     Projects: [],
+    Filesystem: [],
   };
 
   for (const tool of MANAGEMENT_TOOLS) {
diff --git a/apps/mesh/src/web/components/binding-selector.tsx b/apps/mesh/src/web/components/binding-selector.tsx
index b380a04246..cf333617c0 100644
--- a/apps/mesh/src/web/components/binding-selector.tsx
+++ b/apps/mesh/src/web/components/binding-selector.tsx
@@ -3,12 +3,20 @@
  *
  * A reusable connection selector that filters connections by binding.
  * Shows connection icons and supports inline installation from registry.
+ * When running locally, offers a "Choose local folder" option that creates
+ * a @modelcontextprotocol/server-filesystem STDIO connection.
  */
 
-import { useConnections } from "@decocms/mesh-sdk";
+import {
+  useConnections,
+  useConnectionActions,
+  useProjectContext,
+  useMCPClient,
+  SELF_MCP_ALIAS_ID,
+} from "@decocms/mesh-sdk";
 import { useBindingConnections } from "@/web/hooks/use-binding";
 import { useInstallFromRegistry } from "@/web/hooks/use-install-from-registry";
-import { Loading01, Plus } from "@untitledui/icons";
+import { Folder, Loading01, Plus } from "@untitledui/icons";
 import { Button } from "@deco/ui/components/button.tsx";
 import {
   Select,
@@ -59,11 +67,19 @@ export function BindingSelector({
   disabled = false,
 }: BindingSelectorProps) {
   const [isLocalInstalling, setIsLocalInstalling] = useState(false);
+  const [isBrowsing, setIsBrowsing] = useState(false);
   const { installByBinding, isInstalling: isGlobalInstalling } =
     useInstallFromRegistry();
 
   const isInstalling = isLocalInstalling || isGlobalInstalling;
 
+  const { org } = useProjectContext();
+  const { create } = useConnectionActions();
+  const selfClient = useMCPClient({
+    connectionId: SELF_MCP_ALIAS_ID,
+    orgId: org.id,
+  });
+
   const allConnections = useConnections();
 
   // Filter connections based on binding type
@@ -149,8 +165,82 @@ export function BindingSelector({
     onAddNew?.();
   };
 
-  // Get selected connection for display
-  const selectedConnection = connections.find((c) => c.id === value);
+  // Detect if binding requires object storage tools (LIST_OBJECTS, GET_PRESIGNED_URL, etc.)
+  const isObjectStorageBinding = (() => {
+    if (!binding) return false;
+    if (typeof binding === "string") {
+      return binding === "OBJECT_STORAGE";
+    }
+    if (Array.isArray(binding)) {
+      return binding.some(
+        (b) =>
+          b.name === "LIST_OBJECTS" ||
+          b.name === "GET_PRESIGNED_URL" ||
+          b.name === "PUT_PRESIGNED_URL",
+      );
+    }
+    return false;
+  })();
+
+  // Virtual connection ID for dev-assets (local object storage routed through mesh)
+  const devAssetsConnectionId = `${org.id}_dev-assets`;
+
+  const handleChooseLocalFolder = async () => {
+    setIsBrowsing(true);
+    try {
+      // Open native OS folder picker via the mesh server
+      const pickResult = (await selfClient.callTool({
+        name: "FILESYSTEM_PICK_DIRECTORY",
+        arguments: {},
+      })) as { structuredContent?: { path: string | null } };
+
+      const folderPath = pickResult.structuredContent?.path ?? null;
+      if (!folderPath) return;
+
+      const folderName =
+        folderPath.split("/").filter(Boolean).pop() ?? "folder";
+
+      // For object storage bindings, use the local-object-storage bridge
+      // For file/site bindings, use the standard filesystem MCP
+      const connectionConfig = isObjectStorageBinding
+        ? {
+            title: `Local Files: ${folderName}`,
+            connection_type: "STDIO" as const,
+            connection_headers: {
+              command: "node",
+              args: [
+                "--experimental-strip-types",
+                "../../packages/mcp-local-object-storage/src/index.ts",
+                folderPath,
+              ],
+            },
+          }
+        : {
+            title: `Local: ${folderName}`,
+            connection_type: "STDIO" as const,
+            connection_headers: {
+              command: "npx",
+              args: [
+                "-y",
+                "@modelcontextprotocol/server-filesystem",
+                folderPath,
+              ],
+            },
+          };
+
+      const newConnection = await create.mutateAsync(
+        connectionConfig as Parameters<typeof create.mutateAsync>[0],
+      );
+
+      onValueChange(newConnection.id);
+    } catch {
+      // Error is handled by the mutation toast
+    } finally {
+      setIsBrowsing(false);
+    }
+  };
+
+  const busy = isInstalling || isBrowsing;
 
   return (
     <Select
@@ -159,30 +249,24 @@ export function BindingSelector({
       disabled={disabled}
     >
       <SelectTrigger size="sm" className={cn("w-[200px]", className)}>
-        <SelectValue placeholder={placeholder}>
-          {selectedConnection ? (
-            <div className="flex items-center gap-2">
-              {selectedConnection.icon ? (
-                <img
-                  src={selectedConnection.icon}
-                  alt={selectedConnection.title}
-                  className="w-4 h-4 rounded shrink-0"
-                />
-              ) : (
-                <div className="w-4 h-4 rounded bg-gradient-to-br from-primary/20 to-primary/10 flex items-center justify-center text-xs font-semibold text-primary shrink-0">
-                  {selectedConnection.title.slice(0, 1).toUpperCase()}
-                </div>
-              )}
-              <span className="truncate">{selectedConnection.title}</span>
-            </div>
-          ) : (
-            placeholder
-          )}
-        </SelectValue>
+        <SelectValue placeholder={placeholder} />
       </SelectTrigger>
       <SelectContent>
         <SelectItem value="none">No connection</SelectItem>
-        {connections.length === 0 ? (
+        {isObjectStorageBinding && (
+          <SelectItem value={devAssetsConnectionId}>
+            <div className="flex flex-col">
+              <div className="flex items-center gap-2">
+                <Folder size={16} />
+                <span>Local Storage</span>
+              </div>
+              <span className="text-xs text-muted-foreground ml-6">
+                Store in your browser
+              </span>
+            </div>
+          </SelectItem>
+        )}
+        {connections.length === 0 && !isObjectStorageBinding ? (
           <div className="px-2 py-4 text-center text-sm text-muted-foreground">
             No compatible connections found
           </div>
@@ -206,8 +290,39 @@ export function BindingSelector({
             </SelectItem>
           ))
         )}
-        {(onAddNew || canInstallInline) && (
-          <div className="border-t border-border">
+        <div className="border-t border-border flex flex-col">
+          {/* Choose local folder - always available when running locally */}
+          <Button
+            onPointerDown={(e) => e.stopPropagation()}
+            onClick={(e) => {
+              e.preventDefault();
+              e.stopPropagation();
+              handleChooseLocalFolder();
+            }}
+            disabled={busy || disabled}
+            variant="ghost"
+            className="w-full justify-start gap-2 px-2 py-2 h-auto hover:bg-muted rounded-md text-sm disabled:opacity-50 disabled:cursor-not-allowed"
+            type="button"
+          >
+            {isBrowsing ? (
+              <>
+                <Loading01 size={16} className="animate-spin" />
+                <span>Selecting folder...</span>
+              </>
+            ) : (
+              <div className="flex flex-col items-start">
+                <div className="flex items-center gap-2">
+                  <Folder size={16} />
+                  <span>Local Files</span>
+                </div>
+                <span className="text-xs text-muted-foreground ml-6">
+                  Store in your files
+                </span>
+              </div>
+            )}
+          </Button>
+          {/* Add connection / install from registry */}
+          {(onAddNew || canInstallInline) && (
             <Button
               onPointerDown={(e) => e.stopPropagation()}
               onClick={(e) => {
@@ -215,7 +330,7 @@ export function BindingSelector({
                 e.stopPropagation();
                 handleCreateConnection();
               }}
-              disabled={isInstalling || disabled}
+              disabled={busy || disabled}
               variant="ghost"
               className="w-full justify-start gap-2 px-2 py-2 h-auto hover:bg-muted rounded-md text-sm disabled:opacity-50 disabled:cursor-not-allowed"
               type="button"
@@ -228,12 +343,12 @@ export function BindingSelector({
               ) : (
                 <>
                   <Plus size={16} />
-                  <span>Add Connection</span>
+                  <span>Custom Connection</span>
                 </>
               )}
             </Button>
-          </div>
-        )}
+          )}
+        </div>
       </SelectContent>
     </Select>
   );
diff --git a/apps/mesh/src/web/components/details/connection/settings-tab/mcp-configuration-form.tsx b/apps/mesh/src/web/components/details/connection/settings-tab/mcp-configuration-form.tsx
index d4c8b6af0d..488f82798d 100644
--- a/apps/mesh/src/web/components/details/connection/settings-tab/mcp-configuration-form.tsx
+++ b/apps/mesh/src/web/components/details/connection/settings-tab/mcp-configuration-form.tsx
@@ -1,12 +1,15 @@
 import {
   ORG_ADMIN_PROJECT_SLUG,
   useConnections,
+  useConnectionActions,
   useProjectContext,
+  useMCPClient,
+  SELF_MCP_ALIAS_ID,
 } from "@decocms/mesh-sdk";
 import { useBindingConnections } from "@/web/hooks/use-binding";
 import { useBindingSchemaFromRegistry } from "@/web/hooks/use-binding-schema-from-registry";
 import { useInstallFromRegistry } from "@/web/hooks/use-install-from-registry";
-import { Loading01, Plus } from "@untitledui/icons";
+import { Folder, Loading01, Plus } from "@untitledui/icons";
 import { Button } from "@deco/ui/components/button.tsx";
 import {
   Select,
@@ -179,11 +182,19 @@ function BindingSelector({
   className,
 }: BindingSelectorProps) {
   const [isLocalInstalling, setIsLocalInstalling] = useState(false);
+  const [isBrowsing, setIsBrowsing] = useState(false);
   const { installByBinding, isInstalling: isGlobalInstalling } =
     useInstallFromRegistry();
 
   const isInstalling = isLocalInstalling || isGlobalInstalling;
 
+  const { org } = useProjectContext();
+  const { create } = useConnectionActions();
+  const selfClient = useMCPClient({
+    connectionId: SELF_MCP_ALIAS_ID,
+    orgId: org.id,
+  });
+
   const allConnections = useConnections();
   const filteredConnections = useBindingConnections({
     connections: allConnections,
@@ -246,13 +257,102 @@ function BindingSelector({
     onAddNew?.();
   };
 
+  // Detect if binding requires object storage tools
+  const isObjectStorageBinding = (() => {
+    if (!binding) return false;
+    if (typeof binding === "string") {
+      return binding === "OBJECT_STORAGE";
+    }
+    if (Array.isArray(binding)) {
+      return binding.some(
+        (b) =>
+          b.name === "LIST_OBJECTS" ||
+          b.name === "GET_PRESIGNED_URL" ||
+          b.name === "PUT_PRESIGNED_URL",
+      );
+    }
+    return false;
+  })();
+
+  // Virtual connection ID for dev-assets (local object storage routed through mesh)
+  const devAssetsConnectionId = `${org.id}_dev-assets`;
+
+  const handleChooseLocalFolder = async () => {
+    setIsBrowsing(true);
+    try {
+      const pickResult = (await selfClient.callTool({
+        name: "FILESYSTEM_PICK_DIRECTORY",
+        arguments: {},
+      })) as { structuredContent?: { path: string | null } };
+
+      const folderPath = pickResult.structuredContent?.path ?? null;
+      if (!folderPath) return;
+
+      const folderName =
+        folderPath.split("/").filter(Boolean).pop() ?? "folder";
+
+      // For object storage bindings, use the local-object-storage bridge
+      // For file/site bindings, use the standard filesystem MCP
+      const connectionConfig = isObjectStorageBinding
+        ? {
+            title: `Local Files: ${folderName}`,
+            connection_type: "STDIO" as const,
+            connection_headers: {
+              command: "node",
+              args: [
+                "--experimental-strip-types",
+                "../../packages/mcp-local-object-storage/src/index.ts",
+                folderPath,
+              ],
+            },
+          }
+        : {
+            title: `Local: ${folderName}`,
+            connection_type: "STDIO" as const,
+            connection_headers: {
+              command: "npx",
+              args: [
+                "-y",
+                "@modelcontextprotocol/server-filesystem",
+                folderPath,
+              ],
+            },
+          };
+
+      const newConnection = await create.mutateAsync(
+        connectionConfig as Parameters<typeof create.mutateAsync>[0],
+      );
+
+      onValueChange(newConnection.id);
+    } catch {
+      // Error handled by mutation toast
+    } finally {
+      setIsBrowsing(false);
+    }
+  };
+
+  const busy = isInstalling || isBrowsing;
+
   return (
     <Select value={value} onValueChange={onValueChange}>
       <SelectTrigger size="sm" className={cn("w-[200px]", className)}>
         <SelectValue placeholder={placeholder} />
       </SelectTrigger>
       <SelectContent>
-        {connections.length === 0 ? (
+        {isObjectStorageBinding && (
+          <SelectItem value={devAssetsConnectionId}>
+            <div className="flex flex-col">
+              <div className="flex items-center gap-2">
+                <Folder size={16} />
+                <span>Local Storage</span>
+              </div>
+              <span className="text-xs text-muted-foreground ml-6">
+                Store in your browser
+              </span>
+            </div>
+          </SelectItem>
+        )}
+        {connections.length === 0 && !isObjectStorageBinding ? (
           <div className="px-2 py-4 text-center text-sm text-muted-foreground">
             No connections found
           </div>
@@ -276,15 +376,45 @@ function BindingSelector({
             </SelectItem>
           ))
         )}
-        {(onAddNew || canInstallInline) && (
-          <div className="border-t border-border">
+        <div className="border-t border-border flex flex-col">
+          <Button
+            onPointerDown={(e) => e.stopPropagation()}
+            onClick={(e) => {
+              e.preventDefault();
+              e.stopPropagation();
+              handleChooseLocalFolder();
+            }}
+            disabled={busy}
+            variant="ghost"
+            className="w-full justify-start gap-2 px-2 py-2 h-auto hover:bg-muted rounded-md text-sm disabled:opacity-50 disabled:cursor-not-allowed"
+            type="button"
+          >
+            {isBrowsing ? (
+              <>
+                <Loading01 size={16} className="animate-spin" />
+                <span>Selecting folder...</span>
+              </>
+            ) : (
+              <div className="flex flex-col items-start">
+                <div className="flex items-center gap-2">
+                  <Folder size={16} />
+                  <span>Local Files</span>
+                </div>
+                <span className="text-xs text-muted-foreground ml-6">
+                  Store in your files
+                </span>
+              </div>
+            )}
+          </Button>
+          {(onAddNew || canInstallInline) && (
             <Button
+              onPointerDown={(e) => e.stopPropagation()}
               onClick={(e) => {
                 e.preventDefault();
                 e.stopPropagation();
                 handleCreateConnection();
               }}
-              disabled={isInstalling}
+              disabled={busy}
               variant="ghost"
               className="w-full justify-start gap-2 px-2 py-2 h-auto hover:bg-muted rounded-md text-sm disabled:opacity-50 disabled:cursor-not-allowed"
               type="button"
@@ -297,16 +427,12 @@ function BindingSelector({
               ) : (
                 <>
                   <Plus size={16} />
-                  <span>
-                    {canInstallInline
-                      ? "Custom Connection"
-                      : "Custom Connection"}
-                  </span>
+                  <span>Custom Connection</span>
                 </>
               )}
             </Button>
-          </div>
-        )}
+          )}
+        </div>
       </SelectContent>
     </Select>
   );
diff --git a/apps/mesh/src/web/index.tsx b/apps/mesh/src/web/index.tsx
index e815650acd..98bf63a30c 100644
--- a/apps/mesh/src/web/index.tsx
+++ b/apps/mesh/src/web/index.tsx
@@ -345,15 +345,18 @@ const workflowsRoute = createRoute({
 // PLUGIN ROUTES
 // ============================================
 
-const pluginLayoutRoute = createRoute({
-  getParentRoute: () => projectLayout, // Changed from shellLayout
+// Catch-all for unknown/legacy plugins (dynamic $pluginId param).
+// Known plugins get their own static routes below, which TanStack Router
+// prioritizes over this dynamic route.
+const pluginCatchAllRoute = createRoute({
+  getParentRoute: () => projectLayout,
   path: "/$pluginId",
   component: lazyRouteComponent(
     () => import("./layouts/dynamic-plugin-layout.tsx"),
   ),
 });
 
-// Plugin setup (same as before)
+// Plugin setup
 export const pluginRootSidebarItems: {
   pluginId: string;
   icon: ReactNode;
@@ -368,14 +371,28 @@ export const pluginSidebarGroups: {
   defaultExpanded?: boolean;
 }[] = [];
 
-const pluginRoutes: AnyRoute[] = [];
+// Each plugin gets its own static route under projectLayout.
+// This avoids route collisions (e.g. both plugins registering path: "/")
+// because each plugin's children are isolated under their own route.
+const perPluginStaticRoutes: AnyRoute[] = [];
 
 sourcePlugins.forEach((plugin: AnyClientPlugin) => {
-  // Only invoke setup if the plugin provides it
   if (!plugin.setup) return;
 
+  // Static route for this plugin: /site-editor, /object-storage, etc.
+  // Static paths rank higher than $pluginId, so these match first.
+  const pluginRoute = createRoute({
+    getParentRoute: () => projectLayout,
+    path: `/${plugin.id}`,
+    component: lazyRouteComponent(
+      () => import("./layouts/dynamic-plugin-layout.tsx"),
+    ),
+  }) as AnyRoute;
+
+  const perPluginRoutes: AnyRoute[] = [];
+
   const context: PluginSetupContext = {
-    parentRoute: pluginLayoutRoute as AnyRoute,
+    parentRoute: pluginRoute,
     routing: {
       createRoute: createRoute,
       lazyRouteComponent: lazyRouteComponent,
@@ -385,15 +402,14 @@ sourcePlugins.forEach((plugin: AnyClientPlugin) => {
     registerSidebarGroup: (group) =>
       pluginSidebarGroups.push({ pluginId: plugin.id, ...group }),
     registerPluginRoutes: (routes) => {
-      pluginRoutes.push(...routes);
+      perPluginRoutes.push(...routes);
     },
   };
 
   plugin.setup(context);
-});
 
-// Add all plugin routes as children of the plugin layout
-const pluginLayoutWithChildren = pluginLayoutRoute.addChildren(pluginRoutes);
+  perPluginStaticRoutes.push(pluginRoute.addChildren(perPluginRoutes));
+});
 
 // ============================================
 // ROUTE TREE
@@ -417,7 +433,8 @@ const projectRoutes = [
   agentsRoute,
   agentDetailRoute,
   workflowsRoute,
-  pluginLayoutWithChildren,
+  ...perPluginStaticRoutes,
+  pluginCatchAllRoute, // Must be last — $pluginId catch-all
 ];
 
 const projectLayoutWithChildren = projectLayout.addChildren(projectRoutes);
diff --git a/apps/mesh/src/web/layouts/dynamic-plugin-layout.tsx b/apps/mesh/src/web/layouts/dynamic-plugin-layout.tsx
index 2d66016916..fe8c69f805 100644
--- a/apps/mesh/src/web/layouts/dynamic-plugin-layout.tsx
+++ b/apps/mesh/src/web/layouts/dynamic-plugin-layout.tsx
@@ -5,14 +5,27 @@
  * Uses the plugin's renderHeader/renderEmptyState if defined, otherwise falls back to Outlet.
  */
 
-import { Outlet, useParams } from "@tanstack/react-router";
+import { Outlet, useLocation, useParams } from "@tanstack/react-router";
 import { Suspense } from "react";
 import { Loading01 } from "@untitledui/icons";
 import { sourcePlugins } from "../plugins";
 import { PluginLayout } from "./plugin-layout";
 
+/**
+ * Extracts the pluginId from URL params (catch-all $pluginId route) or from
+ * the pathname (per-plugin static routes like /site-editor, /object-storage).
+ * The pluginId is always the 3rd path segment: /$org/$project/$pluginId/...
+ */
+function usePluginId(): string {
+  const params = useParams({ strict: false }) as { pluginId?: string };
+  const location = useLocation();
+  if (params.pluginId) return params.pluginId;
+  const segments = location.pathname.split("/").filter(Boolean);
+  return segments[2] ?? "";
+}
+
 export default function DynamicPluginLayout() {
-  const { pluginId } = useParams({ strict: false }) as { pluginId: string };
+  const pluginId = usePluginId();
 
   // Find the plugin by ID
   const plugin = sourcePlugins.find((p) => p.id === pluginId);
diff --git a/apps/mesh/src/web/layouts/plugin-layout.tsx b/apps/mesh/src/web/layouts/plugin-layout.tsx
index afc1821cb0..e565f05ca0 100644
--- a/apps/mesh/src/web/layouts/plugin-layout.tsx
+++ b/apps/mesh/src/web/layouts/plugin-layout.tsx
@@ -5,13 +5,14 @@
  * and provides PluginContext to plugin routes.
  *
  * Connection selection is controlled by project settings (plugin bindings).
- * If no connection is configured for the plugin, an empty state is shown
- * prompting the user to configure it in project settings.
+ * If no connection is configured for the plugin, the plugin's own empty
+ * state is shown so it can guide the user through setup.
  */
 
 import {
   Binder,
   connectionImplementsBinding,
+  resolveToolNames,
   PluginConnectionEntity,
   PluginContext,
   PluginContextPartial,
@@ -28,12 +29,11 @@ import {
   type ConnectionEntity,
 } from "@decocms/mesh-sdk";
 import { authClient } from "@/web/lib/auth-client";
-import { Outlet, useParams, Link } from "@tanstack/react-router";
-import { Loading01, Settings01 } from "@untitledui/icons";
-import { Suspense, type ReactNode } from "react";
+import { Outlet, useLocation, useParams } from "@tanstack/react-router";
+import { Loading01 } from "@untitledui/icons";
+import { Suspense, useRef, type ReactNode } from "react";
 import { useQuery } from "@tanstack/react-query";
 import { KEYS } from "@/web/lib/query-keys";
-import { Button } from "@deco/ui/components/button.tsx";
 import { Page } from "@/web/components/page";
 
 interface PluginLayoutProps {
@@ -86,6 +86,110 @@ function toPluginConnectionEntity(
   };
 }
 
+/**
+ * Extracts text content from an MCP tool result.
+ * Standard MCP tools return { content: [{ type: "text", text: "..." }] }.
+ */
+function extractMCPText(result: unknown): string {
+  if (!result || typeof result !== "object") return "";
+  const r = result as Record<string, unknown>;
+  // Check structuredContent.content first (newer MCP tools return this)
+  if (r.structuredContent && typeof r.structuredContent === "object") {
+    const sc = r.structuredContent as Record<string, unknown>;
+    if (typeof sc.content === "string") return sc.content;
+  }
+  // Fall back to content array
+  if (Array.isArray(r.content)) {
+    return (r.content as Array<{ type?: string; text?: string }>)
+      .filter((c) => c.type === "text" && c.text)
+      .map((c) => c.text)
+      .join("\n");
+  }
+  return "";
+}
+
+/**
+ * Make a relative path absolute by prepending the root directory.
+ * Matches the server-side site-proxy behavior.
+ */
+function toAbsolute(rootDir: string | null, relativePath: string): string {
+  if (!rootDir || relativePath.startsWith("/")) return relativePath;
+  return `${rootDir.replace(/\/$/, "")}/${relativePath}`;
+}
+
+/**
+ * Adapts binding tool inputs to match the aliased tool's expected schema.
+ * E.g. LIST_FILES({ prefix }) → list_directory({ path }).
+ * Resolves relative paths to absolute using the discovered root directory.
+ */
+function adaptToolInput(
+  canonicalName: string,
+  args: Record<string, unknown>,
+  rootDir: string | null,
+): Record<string, unknown> {
+  switch (canonicalName) {
+    case "LIST_FILES":
+      // LIST_FILES({ prefix }) → list_directory({ path })
+      return { path: toAbsolute(rootDir, (args.prefix as string) || ".") };
+    case "READ_FILE":
+      return { path: toAbsolute(rootDir, (args.path as string) || "") };
+    case "PUT_FILE":
+      return {
+        path: toAbsolute(rootDir, (args.path as string) || ""),
+        content: args.content,
+      };
+    default:
+      return args;
+  }
+}
+
+/**
+ * Adapts standard MCP tool responses to match binding output schemas.
+ * This bridges the gap between e.g. @modelcontextprotocol/server-filesystem
+ * responses and the structured formats bindings expect.
+ */
+function adaptToolResponse(
+  canonicalName: string,
+  rawResult: unknown,
+  originalArgs?: Record<string, unknown>,
+): unknown {
+  const text = extractMCPText(rawResult);
+
+  switch (canonicalName) {
+    case "READ_FILE":
+      // read_file returns text content → { content: string }
+      return { content: text };
+
+    case "PUT_FILE":
+      // write_file returns confirmation text → { success: boolean }
+      return { success: true };
+
+    case "LIST_FILES": {
+      // list_directory returns lines like "[FILE] name.json" and "[DIR] subdir"
+      // We need to reconstruct full paths relative to the queried prefix.
+      const lines = text
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean);
+      const prefix = (originalArgs?.prefix as string) ?? "";
+      const files = lines
+        .filter((l) => l.startsWith("[FILE]"))
+        .map((l) => {
+          const name = l.replace("[FILE]", "").trim();
+          const fullPath =
+            prefix && prefix !== "."
+              ? `${prefix.replace(/\/$/, "")}/${name}`
+              : name;
+          return { path: fullPath, sizeInBytes: 0, mtime: 0 };
+        });
+      return { files, count: files.length };
+    }
+
+    default:
+      return rawResult;
+  }
+}
+
 /**
  * Plugin layout component that filters connections by binding
  * and provides PluginContext to children.
@@ -110,13 +214,11 @@ export function PluginLayout({
   renderEmptyState,
 }: PluginLayoutProps) {
   const { org, project } = useProjectContext();
-  const {
-    org: orgParam,
-    project: projectParam,
-    pluginId,
-  } = useParams({
-    strict: false,
-  }) as { org: string; project: string; pluginId: string };
+  // Extract pluginId from params ($pluginId catch-all) or URL path (static routes)
+  const params = useParams({ strict: false }) as { pluginId?: string };
+  const location = useLocation();
+  const pluginId =
+    params.pluginId ?? location.pathname.split("/").filter(Boolean)[2] ?? "";
   const allConnections = useConnections();
   const { data: authSession } = authClient.useSession();
 
@@ -157,6 +259,11 @@ export function PluginLayout({
     orgId: org.id,
   });
 
+  // Cache the discovered root directory for the filesystem MCP.
+  // Must be called before early returns to satisfy React's Rules of Hooks.
+  // undefined = not yet discovered, null = discovery failed/not applicable, string = root path.
+  const rootDirRef = useRef<string | null | undefined>(undefined);
+
   // Build session for context (always available)
   const session: PluginSession | null = authSession?.user
     ? {
@@ -189,8 +296,8 @@ export function PluginLayout({
     );
   }
 
-  // If no valid connections exist at all, show the plugin's empty state
-  if (validConnections.length === 0) {
+  // If no valid connections or no configured connection, show the plugin's empty state
+  if (validConnections.length === 0 || !configuredConnection) {
     const emptyContext: PluginContextPartial<Binder> = {
       connectionId: null,
       connection: null,
@@ -208,42 +315,35 @@ export function PluginLayout({
     );
   }
 
-  // If no connection is configured in project settings, prompt user to configure
-  if (!configuredConnection) {
-    const emptyContext: PluginContextPartial<Binder> = {
-      connectionId: null,
-      connection: null,
-      toolCaller: null,
-      org: orgContext,
-      session,
-    };
+  // Build tool name mapping for aliased connections (e.g. read_file → READ_FILE)
+  const toolNameMap = resolveToolNames(configuredConnection, binding);
 
-    return (
-      <PluginContextProvider value={emptyContext}>
-        <div className="h-full flex flex-col items-center justify-center gap-4 p-8">
-          <div className="flex flex-col items-center gap-2 text-center max-w-md">
-            <Settings01 size={48} className="text-muted-foreground mb-2" />
-            <h2 className="text-lg font-semibold">Plugin Not Configured</h2>
-            <p className="text-sm text-muted-foreground">
-              This plugin requires a connection to be configured. Go to project
-              settings to select which integration to use.
-            </p>
-          </div>
-          <Button asChild>
-            <Link
-              to="/$org/$project/settings"
-              params={{
-                org: orgParam ?? org.slug,
-                project: projectParam ?? project.slug ?? "",
-              }}
-            >
-              Go to Project Settings
-            </Link>
-          </Button>
-        </div>
-      </PluginContextProvider>
-    );
-  }
+  /**
+   * Discovers the root directory by calling list_allowed_directories on the
+   * MCP connection. Caches the result so subsequent tool calls are instant.
+   */
+  const discoverRootDir = async (): Promise<string | null> => {
+    if (rootDirRef.current !== undefined) return rootDirRef.current;
+    if (!configuredClient) {
+      rootDirRef.current = null;
+      return null;
+    }
+    try {
+      const result = await configuredClient.callTool({
+        name: "list_allowed_directories",
+        arguments: {},
+      });
+      const text = extractMCPText(result);
+      const lines = text
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean);
+      rootDirRef.current = lines.find((l) => l.startsWith("/")) ?? null;
+    } catch {
+      rootDirRef.current = null;
+    }
+    return rootDirRef.current;
+  };
 
   // Create the plugin context with connection
   // TypedToolCaller is generic - the plugin will cast it to the correct binding type
@@ -254,12 +354,32 @@ export function PluginLayout({
     // Type safety is enforced by the plugin using usePluginContext<MyBinding>()
     toolCaller: ((toolName: string, args: unknown) =>
       configuredClient
-        ? configuredClient
-            .callTool({
-              name: toolName,
-              arguments: args as Record<string, unknown>,
-            })
-            .then((result) => result.structuredContent ?? result)
+        ? (async () => {
+            const isAliased = !!toolNameMap[toolName];
+            // Discover root directory on first aliased tool call
+            const rootDir = isAliased ? await discoverRootDir() : null;
+
+            const result = await configuredClient.callTool({
+              name: toolNameMap[toolName] ?? toolName,
+              arguments: (isAliased
+                ? adaptToolInput(
+                    toolName,
+                    args as Record<string, unknown>,
+                    rootDir,
+                  )
+                : args) as Record<string, unknown>,
+            });
+
+            if (isAliased) {
+              return adaptToolResponse(
+                toolName,
+                result,
+                args as Record<string, unknown>,
+              );
+            }
+            const payload = result.structuredContent ?? result;
+            return payload;
+          })()
         : Promise.reject(
             new Error("MCP client is not available"),
           )) as PluginContext<Binder>["toolCaller"],
diff --git a/apps/mesh/src/web/routes/orgs/connections.tsx b/apps/mesh/src/web/routes/orgs/connections.tsx
index 597af1106f..5d799abbfb 100644
--- a/apps/mesh/src/web/routes/orgs/connections.tsx
+++ b/apps/mesh/src/web/routes/orgs/connections.tsx
@@ -126,6 +126,7 @@ const connectionFormSchema = z
     connection_token: z.string().nullable().optional(),
     // For NPX
     npx_package: z.string().optional(),
+    npx_args: z.string().optional(),
     // For STDIO (custom command)
     stdio_command: z.string().optional(),
     stdio_args: z.string().optional(),
@@ -192,7 +193,9 @@ function normalizeUrl(input: string): string {
   }
 }
 
-function parseNpxLikeCommand(input: string): { packageName: string } | null {
+function parseNpxLikeCommand(
+  input: string,
+): { packageName: string; extraArgs: string } | null {
   const tokens = input.trim().split(/\s+/).filter(Boolean);
   if (tokens.length < 2) return null;
 
@@ -201,10 +204,12 @@ function parseNpxLikeCommand(input: string): { packageName: string } | null {
 
   // Skip flags like -y, --yes
   const args = tokens.slice(1);
-  const firstNonFlag = args.find((a) => !a.startsWith("-"));
-  if (!firstNonFlag) return null;
+  const pkgIndex = args.findIndex((a) => !a.startsWith("-"));
+  if (pkgIndex < 0) return null;
 
-  return { packageName: firstNonFlag };
+  const packageName = args[pkgIndex]!;
+  const extraArgs = args.slice(pkgIndex + 1).join(" ");
+  return { packageName, extraArgs };
 }
 
 function inferHardcodedProviderHint(params: {
@@ -294,10 +299,15 @@ function inferRegistryProviderHint(params: {
 function buildNpxParameters(
   packageName: string,
   envVars: EnvVar[],
+  extraArgs?: string,
 ): StdioConnectionParameters {
+  const args = ["-y", packageName];
+  if (extraArgs?.trim()) {
+    args.push(...extraArgs.trim().split(/\s+/));
+  }
   const params: StdioConnectionParameters = {
     command: "npx",
-    args: ["-y", packageName],
+    args,
   };
   const envRecord = envVarsToRecord(envVars);
   if (Object.keys(envRecord).length > 0) {
@@ -345,8 +355,16 @@ function isNpxCommand(params: StdioConnectionParameters): boolean {
 /**
  * Parse STDIO connection_headers back to NPX form fields
  */
-function parseStdioToNpx(params: StdioConnectionParameters): string {
-  return params.args?.find((a) => !a.startsWith("-")) ?? "";
+function parseStdioToNpx(params: StdioConnectionParameters): {
+  packageName: string;
+  extraArgs: string;
+} {
+  const args = params.args ?? [];
+  const packageName = args.find((a) => !a.startsWith("-")) ?? "";
+  // Extra args are everything after the package name (excluding flags like -y)
+  const pkgIndex = args.indexOf(packageName);
+  const extraArgs = pkgIndex >= 0 ? args.slice(pkgIndex + 1).join(" ") : "";
+  return { packageName, extraArgs };
 }
 
 /**
@@ -470,6 +488,7 @@ function OrgMcpsContent() {
       connection_url: "",
       connection_token: null,
       npx_package: "",
+      npx_args: "",
       stdio_command: "",
       stdio_args: "",
       stdio_cwd: "",
@@ -513,14 +532,15 @@ function OrgMcpsContent() {
 
         if (isNpxCommand(stdioParams)) {
           // NPX connection
-          const npxPackage = parseStdioToNpx(stdioParams);
+          const npxParsed = parseStdioToNpx(stdioParams);
           form.reset({
             title: editingConnection.title,
             description: editingConnection.description,
             ui_type: "NPX",
             connection_url: "",
             connection_token: null,
-            npx_package: npxPackage,
+            npx_package: npxParsed.packageName,
+            npx_args: npxParsed.extraArgs,
             stdio_command: "",
             stdio_args: "",
             stdio_cwd: "",
@@ -536,6 +556,7 @@ function OrgMcpsContent() {
             connection_url: "",
             connection_token: null,
             npx_package: "",
+            npx_args: "",
             stdio_command: customData.command,
             stdio_args: customData.args,
             stdio_cwd: customData.cwd,
@@ -699,6 +720,7 @@ function OrgMcpsContent() {
       connectionParameters = buildNpxParameters(
         data.npx_package || "",
         data.env_vars || [],
+        data.npx_args,
       );
     } else if (data.ui_type === "STDIO") {
       // Custom STDIO command
@@ -826,6 +848,7 @@ function OrgMcpsContent() {
     if (npx && stdioEnabled) {
       form.setValue("ui_type", "NPX", { shouldDirty: true });
       form.setValue("npx_package", npx.packageName, { shouldDirty: true });
+      form.setValue("npx_args", npx.extraArgs, { shouldDirty: true });
       // Clear HTTP fields for clarity
       form.setValue("connection_url", "", { shouldDirty: true });
       form.setValue("connection_token", null, { shouldDirty: true });
@@ -1135,6 +1158,26 @@ function OrgMcpsContent() {
                         </FormItem>
                       )}
                     />
+                    <FormField
+                      control={form.control}
+                      name="npx_args"
+                      render={({ field }) => (
+                        <FormItem>
+                          <FormLabel>Arguments</FormLabel>
+                          <FormControl>
+                            <Input
+                              placeholder="/path/to/project --flag value"
+                              {...field}
+                              value={field.value ?? ""}
+                            />
+                          </FormControl>
+                          <p className="text-xs text-muted-foreground">
+                            Additional arguments passed after the package name
+                          </p>
+                          <FormMessage />
+                        </FormItem>
+                      )}
+                    />
                   </>
                 )}
 
diff --git a/packages/bindings/src/core/binder.ts b/packages/bindings/src/core/binder.ts
index e85dfb22f1..d0bf206f3d 100644
--- a/packages/bindings/src/core/binder.ts
+++ b/packages/bindings/src/core/binder.ts
@@ -45,6 +45,13 @@ export interface ToolBinder<
    * If true, an implementation doesn't need to provide this tool.
    */
   opt?: true;
+
+  /**
+   * Alternative tool names that also satisfy this binding slot.
+   * Used for compatibility with standard MCP servers that use different naming.
+   * E.g., READ_FILE might accept ["read_file"] as an alias.
+   */
+  aliases?: string[];
 }
 
 /**
@@ -154,13 +161,20 @@ export function createBindingChecker<TDefinition extends readonly ToolBinder[]>(
   return {
     isImplementedBy: (tools: ToolWithSchemas[]): boolean => {
       for (const binderTool of binderTools) {
-        // Find matching tool by name (exact or regex)
+        // Find matching tool by name (exact or regex), including aliases
         const pattern =
           typeof binderTool.name === "string"
             ? new RegExp(`^${binderTool.name}$`)
             : binderTool.name;
 
-        const matchedTool = tools.find((t) => pattern.test(t.name));
+        const aliasPatterns = (binderTool.aliases ?? []).map(
+          (a) => new RegExp(`^${a}$`),
+        );
+
+        const matchedTool = tools.find(
+          (t) =>
+            pattern.test(t.name) || aliasPatterns.some((ap) => ap.test(t.name)),
+        );
 
         // Skip optional tools that aren't present
         if (!matchedTool && binderTool.opt) {
@@ -215,8 +229,41 @@ export function connectionImplementsBinding(
     name: b.name,
     inputSchema: b.inputSchema,
     opt: b.opt,
+    aliases: b.aliases,
   }));
 
   const checker = createBindingChecker(bindingForChecker);
   return checker.isImplementedBy(toolsForChecker);
 }
+
+/**
+ * Builds a mapping from canonical binding tool names to actual tool names
+ * on the connection. If the connection uses an alias (e.g. "read_file" instead
+ * of "READ_FILE"), the map will contain { READ_FILE: "read_file" }.
+ *
+ * Returns empty map if no aliasing is needed (all canonical names match directly).
+ */
+export function resolveToolNames(
+  connection: ConnectionForBinding,
+  binding: Binder,
+): Record<string, string> {
+  const toolNames = new Set((connection.tools ?? []).map((t) => t.name));
+  const map: Record<string, string> = {};
+
+  for (const binderTool of binding) {
+    const canonicalName =
+      typeof binderTool.name === "string" ? binderTool.name : null;
+    if (!canonicalName) continue;
+
+    // If canonical name exists directly, no mapping needed
+    if (toolNames.has(canonicalName)) continue;
+
+    // Check aliases
+    const matched = (binderTool.aliases ?? []).find((a) => toolNames.has(a));
+    if (matched) {
+      map[canonicalName] = matched;
+    }
+  }
+
+  return map;
+}
diff --git a/packages/bindings/src/core/plugin-router.tsx b/packages/bindings/src/core/plugin-router.tsx
index 367e0e73d6..2731e06d07 100644
--- a/packages/bindings/src/core/plugin-router.tsx
+++ b/packages/bindings/src/core/plugin-router.tsx
@@ -19,6 +19,11 @@ import type { PluginSetupContext } from "./plugins";
 /**
  * Prepends the plugin base path (/$org/$project/$pluginId) to a route path.
  * Handles both absolute plugin paths (starting with /) and relative paths.
+ *
+ * Plugin routes use ID-only layout routes (e.g., "site-editor-layout") as their
+ * root. Route references include this ID (e.g., "/site-editor-layout/pages/$pageId")
+ * but the ID doesn't correspond to a URL segment. This function strips the ID
+ * prefix so the URL is correct (e.g., /$org/$project/site-editor/pages/$pageId).
  */
 function prependBasePath(
   to: string | undefined,
@@ -28,15 +33,36 @@ function prependBasePath(
 ): string {
   if (!to) return `/${org}/${project}/${pluginId}`;
 
-  // If path starts with /, it's relative to the plugin root
   if (to.startsWith("/")) {
-    return `/${org}/${project}/${pluginId}${to}`;
+    // Strip the ID-only layout route prefix.
+    // 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) : "";
+    return `/${org}/${project}/${pluginId}${urlPath}`;
   }
 
-  // Otherwise, it's already a full path or relative
   return to;
 }
 
+/**
+ * Extracts pluginId from params (catch-all $pluginId route) or from the
+ * pathname (per-plugin static routes). The pluginId is always the 3rd segment.
+ */
+function usePluginId(): { org: string; project: string; pluginId: string } {
+  const params = useParams({ strict: false }) as {
+    org: string;
+    project: string;
+    pluginId?: string;
+  };
+  const location = useLocation();
+  const pluginId =
+    params.pluginId ?? location.pathname.split("/").filter(Boolean)[2] ?? "";
+  return { org: params.org, project: params.project, pluginId };
+}
+
 /**
  * Creates a typed plugin router from a route factory function.
  *
@@ -123,11 +149,7 @@ export function createPluginRouter<TRoutes extends AnyRoute | AnyRoute[]>(
      */
     useNavigate: () => {
       const navigate = useNavigate();
-      const { org, project, pluginId } = useParams({ strict: false }) as {
-        org: string;
-        project: string;
-        pluginId: string;
-      };
+      const { org, project, pluginId } = usePluginId();
 
       return <TTo extends TRouteId>(
         options: Omit<NavigateOptions, "to" | "params"> & {
@@ -171,11 +193,7 @@ export function createPluginRouter<TRoutes extends AnyRoute | AnyRoute[]>(
         children?: ReactNode;
       },
     ) {
-      const { org, project, pluginId } = useParams({ strict: false }) as {
-        org: string;
-        project: string;
-        pluginId: string;
-      };
+      const { org, project, pluginId } = usePluginId();
 
       const to = prependBasePath(props.to as string, org, project, pluginId);
 
diff --git a/packages/bindings/src/index.ts b/packages/bindings/src/index.ts
index 67a79a4f58..bc5523ad40 100644
--- a/packages/bindings/src/index.ts
+++ b/packages/bindings/src/index.ts
@@ -10,6 +10,7 @@ export {
   createBindingChecker,
   bindingClient,
   connectionImplementsBinding,
+  resolveToolNames,
   type Binder,
   type BindingChecker,
   type ToolBinder,
diff --git a/packages/bindings/src/well-known/site.ts b/packages/bindings/src/well-known/site.ts
index b026049ab6..e76666bde7 100644
--- a/packages/bindings/src/well-known/site.ts
+++ b/packages/bindings/src/well-known/site.ts
@@ -231,16 +231,19 @@ export const SITE_BINDING = [
     name: "READ_FILE" as const,
     inputSchema: ReadFileInputSchema,
     outputSchema: ReadFileOutputSchema,
+    aliases: ["read_file"],
   } satisfies ToolBinder<"READ_FILE", ReadFileInput, ReadFileOutput>,
   {
     name: "PUT_FILE" as const,
     inputSchema: PutFileInputSchema,
     outputSchema: PutFileOutputSchema,
+    aliases: ["write_file"],
   } satisfies ToolBinder<"PUT_FILE", PutFileInput, PutFileOutput>,
   {
     name: "LIST_FILES" as const,
     inputSchema: ListFilesInputSchema,
     outputSchema: ListFilesOutputSchema,
+    aliases: ["list_directory"],
   } satisfies ToolBinder<"LIST_FILES", ListFilesInput, ListFilesOutput>,
   {
     name: "CREATE_BRANCH" as const,
diff --git a/packages/mesh-plugin-object-storage/components/file-browser.tsx b/packages/mesh-plugin-object-storage/components/file-browser.tsx
index 0a185020b9..a7670bee30 100644
--- a/packages/mesh-plugin-object-storage/components/file-browser.tsx
+++ b/packages/mesh-plugin-object-storage/components/file-browser.tsx
@@ -168,7 +168,7 @@ export default function FileBrowser() {
     flat = false,
     view = "table",
   } = objectStorageRouter.useSearch({
-    from: "/",
+    from: "/object-storage-layout",
   });
   const navigate = objectStorageRouter.useNavigate();
 
@@ -176,14 +176,17 @@ export default function FileBrowser() {
 
   const setPrefix = (newPath: string) => {
     setSelectedKeys(new Set()); // Clear selection when navigating folders
-    navigate({ to: "/", search: { path: newPath || undefined, flat, view } });
+    navigate({
+      to: "/object-storage-layout/",
+      search: { path: newPath || undefined, flat, view },
+    });
   };
 
   const setFlat = (newFlat: boolean) => {
     setSelectedKeys(new Set()); // Clear selection when switching view mode
     // Reset to root when switching to flat mode, preserve path in directory mode
     navigate({
-      to: "/",
+      to: "/object-storage-layout/",
       search: {
         path: newFlat ? undefined : prefix || undefined,
         flat: newFlat,
@@ -195,7 +198,7 @@ export default function FileBrowser() {
   const setView = (newView: "table" | "grid") => {
     setSelectedKeys(new Set()); // Clear selection when switching view
     navigate({
-      to: "/",
+      to: "/object-storage-layout/",
       search: {
         path: prefix || undefined,
         flat,
diff --git a/packages/mesh-plugin-object-storage/lib/router.ts b/packages/mesh-plugin-object-storage/lib/router.ts
index 1abc642503..c931450aec 100644
--- a/packages/mesh-plugin-object-storage/lib/router.ts
+++ b/packages/mesh-plugin-object-storage/lib/router.ts
@@ -6,6 +6,7 @@
  */
 
 import { createPluginRouter } from "@decocms/bindings/plugins";
+import { Outlet } from "@tanstack/react-router";
 import * as z from "zod";
 
 /**
@@ -26,12 +27,20 @@ export type FileBrowserSearch = z.infer<typeof fileBrowserSearchSchema>;
 export const objectStorageRouter = createPluginRouter((ctx) => {
   const { createRoute, lazyRouteComponent } = ctx.routing;
 
-  const indexRoute = createRoute({
+  // Pathless layout route — uses id instead of path to avoid
+  // duplicate "/" collision with other plugins (e.g. site-editor).
+  const layoutRoute = createRoute({
     getParentRoute: () => ctx.parentRoute,
+    id: "object-storage-layout",
+    component: Outlet,
+  });
+
+  const indexRoute = createRoute({
+    getParentRoute: () => layoutRoute,
     path: "/",
     component: lazyRouteComponent(() => import("../components/file-browser")),
     validateSearch: fileBrowserSearchSchema,
   });
 
-  return [indexRoute];
+  return [layoutRoute.addChildren([indexRoute])];
 });
diff --git a/packages/mesh-plugin-site-editor/client/components/block-detail.tsx b/packages/mesh-plugin-site-editor/client/components/block-detail.tsx
index b5e546acb8..fca0d20ec2 100644
--- a/packages/mesh-plugin-site-editor/client/components/block-detail.tsx
+++ b/packages/mesh-plugin-site-editor/client/components/block-detail.tsx
@@ -51,7 +51,7 @@ export default function BlockDetail() {
   const { toolCaller, connectionId } = usePluginContext<typeof SITE_BINDING>();
   const navigate = siteEditorRouter.useNavigate();
   const { blockId } = siteEditorRouter.useParams({
-    from: "/sections/$blockId",
+    from: "/site-editor-layout/sections/$blockId",
   });
 
   const [formData, setFormData] = useState<Record<string, unknown>>({});
@@ -105,7 +105,10 @@ export default function BlockDetail() {
         <p className="text-muted-foreground text-center mb-4">
           The block "{blockId}" could not be found.
         </p>
-        <Button variant="outline" onClick={() => navigate({ to: "/sections" })}>
+        <Button
+          variant="outline"
+          onClick={() => navigate({ to: "/site-editor-layout/sections" })}
+        >
           <ArrowLeft size={14} className="mr-1" />
           Back to Sections
         </Button>
@@ -126,7 +129,7 @@ export default function BlockDetail() {
         <div className="flex items-center gap-2 text-sm">
           <button
             type="button"
-            onClick={() => navigate({ to: "/sections" })}
+            onClick={() => navigate({ to: "/site-editor-layout/sections" })}
             className="text-muted-foreground hover:text-foreground transition-colors"
           >
             Sections
diff --git a/packages/mesh-plugin-site-editor/client/components/loader-detail.tsx b/packages/mesh-plugin-site-editor/client/components/loader-detail.tsx
index 52811e9677..ee69ff9259 100644
--- a/packages/mesh-plugin-site-editor/client/components/loader-detail.tsx
+++ b/packages/mesh-plugin-site-editor/client/components/loader-detail.tsx
@@ -52,7 +52,7 @@ export default function LoaderDetail() {
   const { toolCaller, connectionId } = usePluginContext<typeof SITE_BINDING>();
   const navigate = siteEditorRouter.useNavigate();
   const { loaderId } = siteEditorRouter.useParams({
-    from: "/loaders/$loaderId",
+    from: "/site-editor-layout/loaders/$loaderId",
   });
 
   const [formData, setFormData] = useState<Record<string, unknown>>({});
@@ -107,7 +107,10 @@ export default function LoaderDetail() {
         <p className="text-muted-foreground text-center mb-4">
           The loader &quot;{loaderId}&quot; could not be found.
         </p>
-        <Button variant="outline" onClick={() => navigate({ to: "/loaders" })}>
+        <Button
+          variant="outline"
+          onClick={() => navigate({ to: "/site-editor-layout/loaders" })}
+        >
           <ArrowLeft size={14} className="mr-1" />
           Back to Loaders
         </Button>
@@ -134,7 +137,7 @@ export default function LoaderDetail() {
         <div className="flex items-center gap-2 text-sm">
           <button
             type="button"
-            onClick={() => navigate({ to: "/loaders" })}
+            onClick={() => navigate({ to: "/site-editor-layout/loaders" })}
             className="text-muted-foreground hover:text-foreground transition-colors"
           >
             Loaders
diff --git a/packages/mesh-plugin-site-editor/client/components/loaders-list.tsx b/packages/mesh-plugin-site-editor/client/components/loaders-list.tsx
index bb7d5d990d..f99c2bf8dd 100644
--- a/packages/mesh-plugin-site-editor/client/components/loaders-list.tsx
+++ b/packages/mesh-plugin-site-editor/client/components/loaders-list.tsx
@@ -122,7 +122,7 @@ export default function LoadersList() {
                   type="button"
                   onClick={() =>
                     navigate({
-                      to: "/loaders/$loaderId",
+                      to: "/site-editor-layout/loaders/$loaderId",
                       params: { loaderId: loader.id },
                     })
                   }
diff --git a/packages/mesh-plugin-site-editor/client/components/page-composer.tsx b/packages/mesh-plugin-site-editor/client/components/page-composer.tsx
index bd35081fa7..a2cef1a22b 100644
--- a/packages/mesh-plugin-site-editor/client/components/page-composer.tsx
+++ b/packages/mesh-plugin-site-editor/client/components/page-composer.tsx
@@ -51,7 +51,9 @@ export default function PageComposer() {
   const { toolCaller, connectionId } = usePluginContext<typeof SITE_BINDING>();
   const queryClient = useQueryClient();
   const navigate = siteEditorRouter.useNavigate();
-  const { pageId } = siteEditorRouter.useParams({ from: "/pages/$pageId" });
+  const { pageId } = siteEditorRouter.useParams({
+    from: "/site-editor-layout/pages/$pageId",
+  });
 
   const [selectedBlockId, setSelectedBlockId] = useState<string | null>(null);
   const [viewport, setViewport] = useState<ViewportKey>("desktop");
@@ -343,7 +345,10 @@ export default function PageComposer() {
         <p className="text-muted-foreground text-center mb-4">
           The page &quot;{pageId}&quot; could not be found.
         </p>
-        <Button variant="outline" onClick={() => navigate({ to: "/" })}>
+        <Button
+          variant="outline"
+          onClick={() => navigate({ to: "/site-editor-layout/" })}
+        >
           <ArrowLeft size={14} className="mr-1" />
           Back to Pages
         </Button>
@@ -358,7 +363,7 @@ export default function PageComposer() {
         <div className="flex items-center gap-2 text-sm">
           <button
             type="button"
-            onClick={() => navigate({ to: "/" })}
+            onClick={() => navigate({ to: "/site-editor-layout/" })}
             className="text-muted-foreground hover:text-foreground transition-colors"
           >
             Pages
diff --git a/packages/mesh-plugin-site-editor/client/components/page-editor.tsx b/packages/mesh-plugin-site-editor/client/components/page-editor.tsx
index df5a0fee8b..06a9eaf541 100644
--- a/packages/mesh-plugin-site-editor/client/components/page-editor.tsx
+++ b/packages/mesh-plugin-site-editor/client/components/page-editor.tsx
@@ -10,7 +10,7 @@ import PageComposer from "./page-composer";
 
 export default function PageEditor() {
   // Validate route params are available
-  siteEditorRouter.useParams({ from: "/pages/$pageId" });
+  siteEditorRouter.useParams({ from: "/site-editor-layout/pages/$pageId" });
 
   return <PageComposer />;
 }
diff --git a/packages/mesh-plugin-site-editor/client/components/pages-list.tsx b/packages/mesh-plugin-site-editor/client/components/pages-list.tsx
index 03bbe1d684..8b2d5be62f 100644
--- a/packages/mesh-plugin-site-editor/client/components/pages-list.tsx
+++ b/packages/mesh-plugin-site-editor/client/components/pages-list.tsx
@@ -81,7 +81,7 @@ export default function PagesList() {
       setNewTitle("");
       setNewPath("/");
       navigate({
-        to: "/pages/$pageId",
+        to: "/site-editor-layout/pages/$pageId",
         params: { pageId: page.id },
       });
     },
@@ -230,7 +230,7 @@ export default function PagesList() {
               type="button"
               onClick={() =>
                 navigate({
-                  to: "/pages/$pageId",
+                  to: "/site-editor-layout/pages/$pageId",
                   params: { pageId: page.id },
                 })
               }
diff --git a/packages/mesh-plugin-site-editor/client/components/plugin-empty-state.tsx b/packages/mesh-plugin-site-editor/client/components/plugin-empty-state.tsx
index 182061c2a0..ac8235a36d 100644
--- a/packages/mesh-plugin-site-editor/client/components/plugin-empty-state.tsx
+++ b/packages/mesh-plugin-site-editor/client/components/plugin-empty-state.tsx
@@ -1,20 +1,171 @@
 /**
  * Plugin Empty State Component
  *
- * Shown when no site connections are available.
+ * Shown when no site connections are available or configured.
+ * Provides an inline setup wizard to connect a local project folder.
  */
 
-import { File06 } from "@untitledui/icons";
+import { Folder } from "@untitledui/icons";
+import { useRef, useState } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import { useParams } from "@tanstack/react-router";
+import {
+  useConnectionActions,
+  useProjectContext,
+  useMCPClient,
+  SELF_MCP_ALIAS_ID,
+  KEYS,
+  Locator,
+} from "@decocms/mesh-sdk";
+import { Button } from "@deco/ui/components/button.tsx";
+import { Input } from "@deco/ui/components/input.tsx";
 
 export default function PluginEmptyState() {
+  const [path, setPath] = useState("");
+  const [isConnecting, setIsConnecting] = useState(false);
+  const [isBrowsing, setIsBrowsing] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  const { org, project } = useProjectContext();
+  const { pluginId } = useParams({ strict: false }) as { pluginId: string };
+  const { create } = useConnectionActions();
+  const queryClient = useQueryClient();
+
+  const selfClient = useMCPClient({
+    connectionId: SELF_MCP_ALIAS_ID,
+    orgId: org.id,
+  });
+
+  const handleBrowse = async () => {
+    setIsBrowsing(true);
+    setError(null);
+    try {
+      const result = (await selfClient.callTool({
+        name: "FILESYSTEM_PICK_DIRECTORY",
+        arguments: {},
+      })) as { structuredContent?: { path: string | null } };
+
+      const selected =
+        (result.structuredContent?.path as string | null) ?? null;
+      if (selected) {
+        setPath(selected);
+      }
+    } catch {
+      setError("Could not open folder picker");
+    } finally {
+      setIsBrowsing(false);
+    }
+  };
+
+  const handleConnect = async (e: React.FormEvent) => {
+    e.preventDefault();
+
+    const trimmed = path.trim();
+    if (!trimmed) return;
+
+    setIsConnecting(true);
+    setError(null);
+
+    try {
+      const folderName = trimmed.split("/").filter(Boolean).pop() ?? "site";
+
+      // 1. Create the STDIO connection
+      const newConnection = await create.mutateAsync({
+        title: `Site: ${folderName}`,
+        connection_type: "STDIO",
+        connection_headers: {
+          command: "npx",
+          args: ["-y", "@modelcontextprotocol/server-filesystem", trimmed],
+        },
+      } as Parameters<typeof create.mutateAsync>[0]);
+
+      // 2. Bind the new connection to this plugin via project config
+      await selfClient.callTool({
+        name: "PROJECT_PLUGIN_CONFIG_UPDATE",
+        arguments: {
+          projectId: project.id,
+          pluginId,
+          connectionId: newConnection.id,
+        },
+      });
+
+      // 3. Invalidate queries so PluginLayout re-renders with the connection
+      const locator = Locator.from({
+        org: org.slug,
+        project: project.slug ?? "",
+      });
+      await Promise.all([
+        queryClient.invalidateQueries({
+          queryKey: KEYS.connections(locator),
+        }),
+        queryClient.invalidateQueries({
+          queryKey: ["project-plugin-config", project.id, pluginId],
+        }),
+      ]);
+    } catch (err) {
+      setError(
+        err instanceof Error ? err.message : "Failed to create connection",
+      );
+    } finally {
+      setIsConnecting(false);
+    }
+  };
+
+  const busy = isConnecting || isBrowsing;
+
   return (
     <div className="flex flex-col items-center justify-center h-full p-8">
-      <File06 size={48} className="text-muted-foreground mb-4" />
-      <h3 className="text-lg font-medium mb-2">No site connected</h3>
-      <p className="text-muted-foreground text-center max-w-md">
-        Connect a local-fs MCP server to manage your site's pages, sections, and
-        loaders.
-      </p>
+      <form
+        onSubmit={handleConnect}
+        className="flex flex-col items-center gap-4 w-full max-w-md"
+      >
+        {/* Clickable browse area */}
+        <button
+          type="button"
+          onClick={handleBrowse}
+          disabled={busy}
+          className="flex flex-col items-center gap-3 p-8 w-full border-2 border-dashed border-muted-foreground/25 rounded-lg hover:border-muted-foreground/50 hover:bg-muted/50 transition-colors cursor-pointer disabled:opacity-50 disabled:cursor-not-allowed"
+        >
+          <Folder size={48} className="text-muted-foreground" />
+          <div className="text-center">
+            <h3 className="text-lg font-medium">Connect your site</h3>
+            <p className="text-muted-foreground text-sm mt-1">
+              {isBrowsing
+                ? "Opening folder picker..."
+                : "Click to select a folder"}
+            </p>
+          </div>
+        </button>
+
+        {/* Divider */}
+        <div className="flex items-center gap-3 w-full">
+          <div className="flex-1 h-px bg-border" />
+          <span className="text-xs text-muted-foreground">
+            or enter path manually
+          </span>
+          <div className="flex-1 h-px bg-border" />
+        </div>
+
+        {/* Manual path input */}
+        <Input
+          ref={inputRef}
+          type="text"
+          placeholder="/Users/you/Projects/my-site"
+          value={path}
+          onChange={(e) => setPath(e.target.value)}
+          disabled={busy}
+          className="w-full"
+        />
+
+        {error && (
+          <p className="text-sm text-destructive text-center">{error}</p>
+        )}
+
+        <Button type="submit" disabled={!path.trim() || busy}>
+          {isConnecting ? "Connecting..." : "Connect"}
+        </Button>
+      </form>
     </div>
   );
 }
diff --git a/packages/mesh-plugin-site-editor/client/components/preview-panel.tsx b/packages/mesh-plugin-site-editor/client/components/preview-panel.tsx
index 140e2aa173..bdd5f82fc9 100644
--- a/packages/mesh-plugin-site-editor/client/components/preview-panel.tsx
+++ b/packages/mesh-plugin-site-editor/client/components/preview-panel.tsx
@@ -1,17 +1,21 @@
 /**
  * Preview Panel Component
  *
- * Renders a full-size iframe pointing to the user's running local dev server
- * via the tunnel URL. Communicates with the iframe via a typed postMessage
- * protocol (deco:ready handshake, deco:page-config, deco:select-block).
+ * Renders a full-size iframe pointing to the user's running local dev server.
+ * When no preview URL is configured, shows a form to enter the dev server URL
+ * (e.g., http://localhost:5173 or a deco link tunnel URL).
  *
- * Supports viewport width switching for responsive preview.
+ * The URL is persisted in connection metadata so it survives page reloads.
  */
 
+import { useState } from "react";
 import { useTunnelUrl } from "../lib/use-tunnel-url";
 import { useIframeBridge } from "../lib/use-iframe-bridge";
 import { VIEWPORTS, type ViewportKey } from "./viewport-toggle";
 import type { Page } from "../lib/page-api";
+import { Button } from "@deco/ui/components/button.tsx";
+import { Input } from "@deco/ui/components/input.tsx";
+import { Globe02, Loading01, LinkExternal01 } from "@untitledui/icons";
 
 interface PreviewPanelProps {
   /** Page path to preview (e.g., "/", "/about") */
@@ -33,12 +37,13 @@ export function PreviewPanel({
   viewport,
   onBlockClicked,
 }: PreviewPanelProps) {
-  const { url, isLoading } = useTunnelUrl();
+  const { url, isLoading, setPreviewUrl, isSaving } = useTunnelUrl();
   const { setIframeRef } = useIframeBridge({
     page,
     selectedBlockId,
     onBlockClicked,
   });
+  const [inputUrl, setInputUrl] = useState("http://localhost:5173");
 
   if (isLoading) {
     return (
@@ -52,14 +57,45 @@ export function PreviewPanel({
 
   if (!url) {
     return (
-      <div className="flex flex-col items-center justify-center h-full gap-4 text-muted-foreground">
-        <p className="text-lg font-medium">No preview available</p>
-        <p className="text-sm">
-          Start your dev server and run{" "}
-          <code className="px-1.5 py-0.5 bg-muted rounded text-xs font-mono">
+      <div className="flex flex-col items-center justify-center h-full gap-6 text-muted-foreground px-8">
+        <Globe02 size={48} className="text-muted-foreground/50" />
+        <div className="text-center">
+          <p className="text-lg font-medium text-foreground mb-1">
+            Connect your dev server
+          </p>
+          <p className="text-sm">
+            Enter your local dev server URL to see a live preview
+          </p>
+        </div>
+        <form
+          className="flex items-center gap-2 w-full max-w-md"
+          onSubmit={(e) => {
+            e.preventDefault();
+            if (inputUrl.trim()) {
+              setPreviewUrl(inputUrl.trim());
+            }
+          }}
+        >
+          <Input
+            value={inputUrl}
+            onChange={(e) => setInputUrl(e.target.value)}
+            placeholder="http://localhost:5173"
+            className="flex-1"
+          />
+          <Button type="submit" disabled={!inputUrl.trim() || isSaving}>
+            {isSaving ? (
+              <Loading01 size={14} className="animate-spin mr-1" />
+            ) : (
+              <LinkExternal01 size={14} className="mr-1" />
+            )}
+            Connect
+          </Button>
+        </form>
+        <p className="text-xs text-muted-foreground/70">
+          Or use a tunnel URL from{" "}
+          <code className="px-1 py-0.5 bg-muted rounded text-xs font-mono">
             deco link
-          </code>{" "}
-          to see a live preview
+          </code>
         </p>
       </div>
     );
diff --git a/packages/mesh-plugin-site-editor/client/components/sections-list.tsx b/packages/mesh-plugin-site-editor/client/components/sections-list.tsx
index 68506979ae..7a3a3e0f59 100644
--- a/packages/mesh-plugin-site-editor/client/components/sections-list.tsx
+++ b/packages/mesh-plugin-site-editor/client/components/sections-list.tsx
@@ -122,7 +122,7 @@ export default function SectionsList() {
                   type="button"
                   onClick={() =>
                     navigate({
-                      to: "/sections/$blockId",
+                      to: "/site-editor-layout/sections/$blockId",
                       params: { blockId: block.id },
                     })
                   }
diff --git a/packages/mesh-plugin-site-editor/client/lib/router.ts b/packages/mesh-plugin-site-editor/client/lib/router.ts
index 12e73e117a..79018cbdc2 100644
--- a/packages/mesh-plugin-site-editor/client/lib/router.ts
+++ b/packages/mesh-plugin-site-editor/client/lib/router.ts
@@ -3,9 +3,14 @@
  *
  * Provides typed routing utilities for the site editor plugin.
  * Uses createPluginRouter to get typed useSearch, useNavigate, etc.
+ *
+ * Routes are wrapped in a pathless layout route (id-only) to avoid
+ * colliding with other plugins that also register path: "/" under
+ * the shared pluginLayoutRoute parent.
  */
 
 import { createPluginRouter } from "@decocms/bindings/plugins";
+import { Outlet } from "@tanstack/react-router";
 
 /**
  * Plugin router with typed hooks for navigation and search params.
@@ -13,48 +18,60 @@ import { createPluginRouter } from "@decocms/bindings/plugins";
 export const siteEditorRouter = createPluginRouter((ctx) => {
   const { createRoute, lazyRouteComponent } = ctx.routing;
 
-  const pagesRoute = createRoute({
+  // Pathless layout route — uses id instead of path to avoid
+  // duplicate "/" collision with other plugins (e.g. object-storage).
+  const layoutRoute = createRoute({
     getParentRoute: () => ctx.parentRoute,
+    id: "site-editor-layout",
+    component: Outlet,
+  });
+
+  const pagesRoute = createRoute({
+    getParentRoute: () => layoutRoute,
     path: "/",
     component: lazyRouteComponent(() => import("../components/pages-list")),
   });
 
   const pageEditorRoute = createRoute({
-    getParentRoute: () => ctx.parentRoute,
+    getParentRoute: () => layoutRoute,
     path: "/pages/$pageId",
     component: lazyRouteComponent(() => import("../components/page-editor")),
   });
 
   const sectionsRoute = createRoute({
-    getParentRoute: () => ctx.parentRoute,
+    getParentRoute: () => layoutRoute,
     path: "/sections",
     component: lazyRouteComponent(() => import("../components/sections-list")),
   });
 
   const blockDetailRoute = createRoute({
-    getParentRoute: () => ctx.parentRoute,
+    getParentRoute: () => layoutRoute,
     path: "/sections/$blockId",
     component: lazyRouteComponent(() => import("../components/block-detail")),
   });
 
   const loadersRoute = createRoute({
-    getParentRoute: () => ctx.parentRoute,
+    getParentRoute: () => layoutRoute,
     path: "/loaders",
     component: lazyRouteComponent(() => import("../components/loaders-list")),
   });
 
   const loaderDetailRoute = createRoute({
-    getParentRoute: () => ctx.parentRoute,
+    getParentRoute: () => layoutRoute,
     path: "/loaders/$loaderId",
     component: lazyRouteComponent(() => import("../components/loader-detail")),
   });
 
+  // Return the layout route with all children nested under it.
+  // Only the layout gets added to pluginRoutes — no "/" collision.
   return [
-    pagesRoute,
-    pageEditorRoute,
-    sectionsRoute,
-    blockDetailRoute,
-    loadersRoute,
-    loaderDetailRoute,
+    layoutRoute.addChildren([
+      pagesRoute,
+      pageEditorRoute,
+      sectionsRoute,
+      blockDetailRoute,
+      loadersRoute,
+      loaderDetailRoute,
+    ]),
   ];
 });
diff --git a/packages/mesh-plugin-site-editor/client/lib/use-tunnel-url.ts b/packages/mesh-plugin-site-editor/client/lib/use-tunnel-url.ts
index 86548e02b4..2c6b974985 100644
--- a/packages/mesh-plugin-site-editor/client/lib/use-tunnel-url.ts
+++ b/packages/mesh-plugin-site-editor/client/lib/use-tunnel-url.ts
@@ -2,43 +2,77 @@
  * Hook to resolve the tunnel URL for the site preview.
  *
  * The tunnel URL is how users see their running local dev server in the
- * Mesh admin. They start their dev server locally, run `deco link` to
- * create a tunnel, and this hook resolves the preview URL.
+ * Mesh admin. They start their dev server locally and either:
+ * - Enter the local URL (e.g., http://localhost:5173) directly
+ * - Run `deco link` and use the generated tunnel URL
  *
- * For Phase 1, the tunnel URL is extracted from the connection's metadata.
- * The connection metadata may contain a `previewUrl` field set during
- * `deco link`, or we fall back to null (showing a placeholder).
+ * The URL is persisted in the connection's metadata.previewUrl field
+ * via COLLECTION_CONNECTIONS_UPDATE so it survives page reloads.
  */
 
+import { useState } from "react";
 import { usePluginContext } from "@decocms/mesh-sdk/plugins";
 import { SITE_BINDING } from "@decocms/bindings";
+import {
+  SELF_MCP_ALIAS_ID,
+  useMCPClient,
+  useProjectContext,
+} from "@decocms/mesh-sdk";
+import { useQueryClient } from "@tanstack/react-query";
 
 export interface UseTunnelUrlResult {
   /** The resolved tunnel URL, or null if not available */
   url: string | null;
   /** Whether the URL is still being resolved */
   isLoading: boolean;
+  /** Set the preview URL and persist it to connection metadata */
+  setPreviewUrl: (url: string) => Promise<void>;
+  /** Whether setPreviewUrl is in progress */
+  isSaving: boolean;
 }
 
 /**
  * Resolves the tunnel URL from the plugin context's connection metadata.
- *
- * The connection metadata may contain:
- * - `previewUrl`: The URL to the running local dev server (set by `deco link`)
- *
- * Returns null when no tunnel URL is configured, which causes the
- * PreviewPanel to show instructions for running `deco link`.
+ * Also provides a setter to persist a new preview URL.
  */
 export function useTunnelUrl(): UseTunnelUrlResult {
-  const { connection } = usePluginContext<typeof SITE_BINDING>();
+  const { connection, connectionId } = usePluginContext<typeof SITE_BINDING>();
+  const { org } = useProjectContext();
+  const selfClient = useMCPClient({
+    connectionId: SELF_MCP_ALIAS_ID,
+    orgId: org.id,
+  });
+  const queryClient = useQueryClient();
+  const [isSaving, setIsSaving] = useState(false);
 
-  // The preview URL lives in connection metadata, set by `deco link`.
-  // The metadata field is Record<string, unknown> | null on the connection entity.
   const metadata = connection?.metadata;
   const previewUrl =
     metadata && typeof metadata.previewUrl === "string"
       ? metadata.previewUrl
       : null;
 
-  return { url: previewUrl, isLoading: false };
+  const setPreviewUrl = async (url: string) => {
+    if (!connectionId) return;
+    setIsSaving(true);
+    try {
+      await selfClient.callTool({
+        name: "COLLECTION_CONNECTIONS_UPDATE",
+        arguments: {
+          id: connectionId,
+          data: {
+            metadata: {
+              ...((metadata as Record<string, unknown>) ?? {}),
+              previewUrl: url,
+            },
+          },
+        },
+      });
+      // Invalidate connections query so the new metadata is picked up
+      queryClient.invalidateQueries();
+    } finally {
+      setIsSaving(false);
+    }
+  };
+
+  return { url: previewUrl, isLoading: false, setPreviewUrl, isSaving };
 }
diff --git a/packages/mesh-plugin-site-editor/package.json b/packages/mesh-plugin-site-editor/package.json
index 724474fc30..2d404c390a 100644
--- a/packages/mesh-plugin-site-editor/package.json
+++ b/packages/mesh-plugin-site-editor/package.json
@@ -26,6 +26,7 @@
     "lucide-react": "^0.468.0",
     "ts-morph": "^27.0.2",
     "ts-json-schema-generator": "^2.4.0",
+    "sonner": ">=2.0.0",
     "zod": "^4.0.0"
   },
   "devDependencies": {
diff --git a/packages/mesh-plugin-site-editor/server/site-proxy.ts b/packages/mesh-plugin-site-editor/server/site-proxy.ts
new file mode 100644
index 0000000000..27617cae64
--- /dev/null
+++ b/packages/mesh-plugin-site-editor/server/site-proxy.ts
@@ -0,0 +1,184 @@
+/**
+ * Site Proxy
+ *
+ * Wraps an MCP proxy with SITE_BINDING awareness so server-side tools
+ * can call canonical names (LIST_FILES, READ_FILE, PUT_FILE) even when
+ * the connection only exposes aliases (list_directory, read_file, write_file).
+ *
+ * Also resolves relative paths to absolute paths using the MCP's allowed
+ * directory, since the filesystem MCP resolves relative paths against its
+ * CWD (which may differ from the allowed directory).
+ *
+ * Input adaptation:
+ * - LIST_FILES { prefix } → list_directory { path: "<root>/<prefix>" }
+ * - READ_FILE { path } → read_file { path: "<root>/<path>" }
+ * - PUT_FILE { path, content } → write_file { path: "<root>/<path>", content }
+ *
+ * Output adaptation:
+ * - list_directory text ("[FILE] x\n[DIR] y") → LIST_FILES JSON ({ files, count })
+ */
+
+import { SITE_BINDING } from "@decocms/bindings/site";
+
+type MCPProxy = {
+  callTool: (args: {
+    name: string;
+    arguments?: Record<string, unknown>;
+  }) => Promise<{
+    isError?: boolean;
+    content?: Array<{ type?: string; text?: string }>;
+    structuredContent?: unknown;
+  }>;
+  listTools: () => Promise<{
+    tools: Array<{ name: string; description?: string }>;
+  }>;
+  close?: () => Promise<void>;
+};
+
+export type SiteProxy = Pick<MCPProxy, "callTool" | "close">;
+
+/**
+ * Extract the first allowed directory from the filesystem MCP.
+ * Returns null if the tool isn't available or returns unexpected format.
+ */
+async function discoverRootDir(
+  proxy: MCPProxy,
+  toolNames: Set<string>,
+): Promise<string | null> {
+  if (!toolNames.has("list_allowed_directories")) return null;
+  try {
+    const result = await proxy.callTool({
+      name: "list_allowed_directories",
+      arguments: {},
+    });
+    // structuredContent.content or content[0].text, format: "Allowed directories:\n/path/to/dir"
+    const text =
+      (typeof (result.structuredContent as Record<string, unknown>)?.content ===
+      "string"
+        ? (result.structuredContent as Record<string, string>).content
+        : null) ??
+      result.content?.[0]?.text ??
+      "";
+    const lines = text
+      .split("\n")
+      .map((l) => l.trim())
+      .filter(Boolean);
+    // Find first line that looks like an absolute path
+    return lines.find((l) => l.startsWith("/")) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Make a relative path absolute by prepending the root directory.
+ */
+function toAbsolute(rootDir: string | null, relativePath: string): string {
+  if (!rootDir || relativePath.startsWith("/")) return relativePath;
+  return `${rootDir.replace(/\/$/, "")}/${relativePath}`;
+}
+
+/**
+ * Wraps an MCP proxy so canonical SITE_BINDING tool names
+ * are resolved to the actual tool names on the connection.
+ */
+export async function createSiteProxy(proxy: MCPProxy): Promise<SiteProxy> {
+  const { tools } = await proxy.listTools();
+  const toolNames = new Set(tools.map((t) => t.name));
+
+  // Build canonical → actual name map
+  const nameMap: Record<string, string> = {};
+  for (const binder of SITE_BINDING) {
+    const canonical = binder.name;
+    if (toolNames.has(canonical)) continue;
+    const alias = (binder as { aliases?: string[] }).aliases?.find(
+      (a: string) => toolNames.has(a),
+    );
+    if (alias) {
+      nameMap[canonical] = alias;
+    }
+  }
+
+  // Discover root directory for resolving relative paths
+  const rootDir =
+    Object.keys(nameMap).length > 0
+      ? await discoverRootDir(proxy, toolNames)
+      : null;
+
+  return {
+    callTool: async (args) => {
+      const actualName = nameMap[args.name];
+      if (!actualName) {
+        return proxy.callTool(args);
+      }
+
+      const originalArgs = args.arguments ?? {};
+
+      // Adapt input based on canonical tool name
+      let adaptedArgs: Record<string, unknown>;
+      switch (args.name) {
+        case "LIST_FILES":
+          adaptedArgs = {
+            path: toAbsolute(rootDir, (originalArgs.prefix as string) || "."),
+          };
+          break;
+        case "READ_FILE":
+          adaptedArgs = {
+            path: toAbsolute(rootDir, (originalArgs.path as string) || ""),
+          };
+          break;
+        case "PUT_FILE":
+          adaptedArgs = {
+            path: toAbsolute(rootDir, (originalArgs.path as string) || ""),
+            content: originalArgs.content,
+          };
+          break;
+        default:
+          adaptedArgs = originalArgs;
+      }
+
+      const result = await proxy.callTool({
+        name: actualName,
+        arguments: adaptedArgs,
+      });
+
+      // Adapt output for LIST_FILES (text lines → structured JSON)
+      // list_directory may return structuredContent.content (a string) or content[0].text
+      if (args.name === "LIST_FILES") {
+        const text =
+          (typeof (result.structuredContent as Record<string, unknown>)
+            ?.content === "string"
+            ? (result.structuredContent as Record<string, string>).content
+            : null) ??
+          result.content?.[0]?.text ??
+          "";
+        const lines = text
+          .split("\n")
+          .map((l) => l.trim())
+          .filter(Boolean);
+        const prefix = (originalArgs.prefix as string) ?? "";
+        const files = lines
+          .filter((l) => l.startsWith("[FILE]"))
+          .map((l) => {
+            const name = l.replace("[FILE]", "").trim();
+            const fullPath =
+              prefix && prefix !== "."
+                ? `${prefix.replace(/\/$/, "")}/${name}`
+                : name;
+            return { path: fullPath, sizeInBytes: 0, mtime: 0 };
+          });
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ files, count: files.length }),
+            },
+          ],
+        };
+      }
+
+      return result;
+    },
+    close: proxy.close,
+  };
+}
diff --git a/packages/mesh-plugin-site-editor/server/tools/block-get.ts b/packages/mesh-plugin-site-editor/server/tools/block-get.ts
index f12a5a72c0..c70219c6b0 100644
--- a/packages/mesh-plugin-site-editor/server/tools/block-get.ts
+++ b/packages/mesh-plugin-site-editor/server/tools/block-get.ts
@@ -7,6 +7,7 @@
 
 import { z } from "zod";
 import type { ServerPluginToolDefinition } from "@decocms/bindings/server-plugin";
+import { createSiteProxy } from "../site-proxy";
 
 export const BLOCK_GET: ServerPluginToolDefinition = {
   name: "CMS_BLOCK_GET",
@@ -41,7 +42,7 @@ export const BLOCK_GET: ServerPluginToolDefinition = {
       connectionId: string;
       blockId: string;
     };
-    const proxy = await ctx.createMCPProxy(connectionId);
+    const proxy = await createSiteProxy(await ctx.createMCPProxy(connectionId));
 
     try {
       const readResult = await proxy.callTool({
diff --git a/packages/mesh-plugin-site-editor/server/tools/block-list.ts b/packages/mesh-plugin-site-editor/server/tools/block-list.ts
index ef52a8d59c..9f18ac9e97 100644
--- a/packages/mesh-plugin-site-editor/server/tools/block-list.ts
+++ b/packages/mesh-plugin-site-editor/server/tools/block-list.ts
@@ -7,6 +7,7 @@
 
 import { z } from "zod";
 import type { ServerPluginToolDefinition } from "@decocms/bindings/server-plugin";
+import { createSiteProxy } from "../site-proxy";
 
 export const BLOCK_LIST: ServerPluginToolDefinition = {
   name: "CMS_BLOCK_LIST",
@@ -29,7 +30,7 @@ export const BLOCK_LIST: ServerPluginToolDefinition = {
 
   handler: async (input, ctx) => {
     const { connectionId } = input as { connectionId: string };
-    const proxy = await ctx.createMCPProxy(connectionId);
+    const proxy = await createSiteProxy(await ctx.createMCPProxy(connectionId));
 
     try {
       const listResult = await proxy.callTool({
diff --git a/packages/mesh-plugin-site-editor/server/tools/block-register.ts b/packages/mesh-plugin-site-editor/server/tools/block-register.ts
index 50db2e1f5e..5a7a176dd5 100644
--- a/packages/mesh-plugin-site-editor/server/tools/block-register.ts
+++ b/packages/mesh-plugin-site-editor/server/tools/block-register.ts
@@ -7,6 +7,7 @@
 
 import { z } from "zod";
 import type { ServerPluginToolDefinition } from "@decocms/bindings/server-plugin";
+import { createSiteProxy } from "../site-proxy";
 
 /**
  * Derive a block ID from a component path.
@@ -62,7 +63,7 @@ export const BLOCK_REGISTER: ServerPluginToolDefinition = {
         defaults?: Record<string, unknown>;
       };
     };
-    const proxy = await ctx.createMCPProxy(connectionId);
+    const proxy = await createSiteProxy(await ctx.createMCPProxy(connectionId));
 
     try {
       const id = componentToId(blockInput.component);
diff --git a/packages/mesh-plugin-site-editor/server/tools/block-scan.ts b/packages/mesh-plugin-site-editor/server/tools/block-scan.ts
index e46b4e02f8..33ab7334b2 100644
--- a/packages/mesh-plugin-site-editor/server/tools/block-scan.ts
+++ b/packages/mesh-plugin-site-editor/server/tools/block-scan.ts
@@ -9,6 +9,7 @@
 
 import { z } from "zod";
 import type { ServerPluginToolDefinition } from "@decocms/bindings/server-plugin";
+import { createSiteProxy } from "../site-proxy";
 import { createProjectFromMCP } from "../scanner/extract.js";
 import { discoverComponents } from "../scanner/discover.js";
 import { generateSchema } from "../scanner/schema.js";
@@ -74,7 +75,7 @@ export const BLOCK_SCAN: ServerPluginToolDefinition = {
       connectionId: string;
       patterns?: string[];
     };
-    const proxy = await ctx.createMCPProxy(connectionId);
+    const proxy = await createSiteProxy(await ctx.createMCPProxy(connectionId));
 
     const blocks: BlockSummary[] = [];
     const errors: string[] = [];
diff --git a/packages/mesh-plugin-site-editor/server/tools/loader-get.ts b/packages/mesh-plugin-site-editor/server/tools/loader-get.ts
index 35f73b1d37..18bcc48f20 100644
--- a/packages/mesh-plugin-site-editor/server/tools/loader-get.ts
+++ b/packages/mesh-plugin-site-editor/server/tools/loader-get.ts
@@ -7,6 +7,7 @@
 
 import { z } from "zod";
 import type { ServerPluginToolDefinition } from "@decocms/bindings/server-plugin";
+import { createSiteProxy } from "../site-proxy";
 
 export const LOADER_GET: ServerPluginToolDefinition = {
   name: "CMS_LOADER_GET",
@@ -43,7 +44,7 @@ export const LOADER_GET: ServerPluginToolDefinition = {
       connectionId: string;
       loaderId: string;
     };
-    const proxy = await ctx.createMCPProxy(connectionId);
+    const proxy = await createSiteProxy(await ctx.createMCPProxy(connectionId));
 
     try {
       const readResult = await proxy.callTool({
diff --git a/packages/mesh-plugin-site-editor/server/tools/loader-list.ts b/packages/mesh-plugin-site-editor/server/tools/loader-list.ts
index 34636793a6..b987600b36 100644
--- a/packages/mesh-plugin-site-editor/server/tools/loader-list.ts
+++ b/packages/mesh-plugin-site-editor/server/tools/loader-list.ts
@@ -7,6 +7,7 @@
 
 import { z } from "zod";
 import type { ServerPluginToolDefinition } from "@decocms/bindings/server-plugin";
+import { createSiteProxy } from "../site-proxy";
 
 export const LOADER_LIST: ServerPluginToolDefinition = {
   name: "CMS_LOADER_LIST",
@@ -29,7 +30,7 @@ export const LOADER_LIST: ServerPluginToolDefinition = {
 
   handler: async (input, ctx) => {
     const { connectionId } = input as { connectionId: string };
-    const proxy = await ctx.createMCPProxy(connectionId);
+    const proxy = await createSiteProxy(await ctx.createMCPProxy(connectionId));
 
     try {
       const listResult = await proxy.callTool({
diff --git a/packages/mesh-plugin-site-editor/server/tools/loader-scan.ts b/packages/mesh-plugin-site-editor/server/tools/loader-scan.ts
index d5df8c8259..548bca3efb 100644
--- a/packages/mesh-plugin-site-editor/server/tools/loader-scan.ts
+++ b/packages/mesh-plugin-site-editor/server/tools/loader-scan.ts
@@ -10,6 +10,7 @@
 
 import { z } from "zod";
 import type { ServerPluginToolDefinition } from "@decocms/bindings/server-plugin";
+import { createSiteProxy } from "../site-proxy";
 import { createProjectFromMCP } from "../scanner/extract.js";
 import { discoverLoaders } from "../scanner/discover.js";
 import { generateSchema } from "../scanner/schema.js";
@@ -73,7 +74,7 @@ export const LOADER_SCAN: ServerPluginToolDefinition = {
       connectionId: string;
       patterns?: string[];
     };
-    const proxy = await ctx.createMCPProxy(connectionId);
+    const proxy = await createSiteProxy(await ctx.createMCPProxy(connectionId));
 
     const loaders: LoaderSummary[] = [];
     const errors: string[] = [];
diff --git a/packages/mesh-plugin-site-editor/server/tools/page-create.ts b/packages/mesh-plugin-site-editor/server/tools/page-create.ts
index 4fa913b143..23ba7909a4 100644
--- a/packages/mesh-plugin-site-editor/server/tools/page-create.ts
+++ b/packages/mesh-plugin-site-editor/server/tools/page-create.ts
@@ -8,6 +8,7 @@
 import { z } from "zod";
 import { nanoid } from "nanoid";
 import type { ServerPluginToolDefinition } from "@decocms/bindings/server-plugin";
+import { createSiteProxy } from "../site-proxy";
 
 const PageSchema = z.object({
   id: z.string(),
@@ -39,7 +40,7 @@ export const PAGE_CREATE: ServerPluginToolDefinition = {
       title: string;
       path: string;
     };
-    const proxy = await ctx.createMCPProxy(connectionId);
+    const proxy = await createSiteProxy(await ctx.createMCPProxy(connectionId));
 
     try {
       const id = `page_${nanoid(8)}`;
diff --git a/packages/mesh-plugin-site-editor/server/tools/page-delete.ts b/packages/mesh-plugin-site-editor/server/tools/page-delete.ts
index f182f91527..e6cfe1db06 100644
--- a/packages/mesh-plugin-site-editor/server/tools/page-delete.ts
+++ b/packages/mesh-plugin-site-editor/server/tools/page-delete.ts
@@ -12,6 +12,7 @@
 
 import { z } from "zod";
 import type { ServerPluginToolDefinition } from "@decocms/bindings/server-plugin";
+import { createSiteProxy } from "../site-proxy";
 
 export const PAGE_DELETE: ServerPluginToolDefinition = {
   name: "CMS_PAGE_DELETE",
@@ -29,7 +30,7 @@ export const PAGE_DELETE: ServerPluginToolDefinition = {
       connectionId: string;
       pageId: string;
     };
-    const proxy = await ctx.createMCPProxy(connectionId);
+    const proxy = await createSiteProxy(await ctx.createMCPProxy(connectionId));
 
     try {
       const filePath = `.deco/pages/${pageId}.json`;
diff --git a/packages/mesh-plugin-site-editor/server/tools/page-get.ts b/packages/mesh-plugin-site-editor/server/tools/page-get.ts
index 8b7425396d..0cc026d162 100644
--- a/packages/mesh-plugin-site-editor/server/tools/page-get.ts
+++ b/packages/mesh-plugin-site-editor/server/tools/page-get.ts
@@ -6,6 +6,7 @@
 
 import { z } from "zod";
 import type { ServerPluginToolDefinition } from "@decocms/bindings/server-plugin";
+import { createSiteProxy } from "../site-proxy";
 
 const PageSchema = z.object({
   id: z.string(),
@@ -35,7 +36,7 @@ export const PAGE_GET: ServerPluginToolDefinition = {
       connectionId: string;
       pageId: string;
     };
-    const proxy = await ctx.createMCPProxy(connectionId);
+    const proxy = await createSiteProxy(await ctx.createMCPProxy(connectionId));
 
     try {
       const readResult = await proxy.callTool({
diff --git a/packages/mesh-plugin-site-editor/server/tools/page-list.ts b/packages/mesh-plugin-site-editor/server/tools/page-list.ts
index 98db784f45..f70b98c359 100644
--- a/packages/mesh-plugin-site-editor/server/tools/page-list.ts
+++ b/packages/mesh-plugin-site-editor/server/tools/page-list.ts
@@ -7,6 +7,7 @@
 
 import { z } from "zod";
 import type { ServerPluginToolDefinition } from "@decocms/bindings/server-plugin";
+import { createSiteProxy } from "../site-proxy";
 
 const PageSummarySchema = z.object({
   id: z.string(),
@@ -28,7 +29,7 @@ export const PAGE_LIST: ServerPluginToolDefinition = {
 
   handler: async (input, ctx) => {
     const { connectionId } = input as { connectionId: string };
-    const proxy = await ctx.createMCPProxy(connectionId);
+    const proxy = await createSiteProxy(await ctx.createMCPProxy(connectionId));
 
     try {
       // List files under .deco/pages/
diff --git a/packages/mesh-plugin-site-editor/server/tools/page-update.ts b/packages/mesh-plugin-site-editor/server/tools/page-update.ts
index 89163920d8..dd18c377b3 100644
--- a/packages/mesh-plugin-site-editor/server/tools/page-update.ts
+++ b/packages/mesh-plugin-site-editor/server/tools/page-update.ts
@@ -7,6 +7,7 @@
 
 import { z } from "zod";
 import type { ServerPluginToolDefinition } from "@decocms/bindings/server-plugin";
+import { createSiteProxy } from "../site-proxy";
 
 const PageSchema = z.object({
   id: z.string(),
@@ -43,7 +44,7 @@ export const PAGE_UPDATE: ServerPluginToolDefinition = {
       path?: string;
       blocks?: unknown[];
     };
-    const proxy = await ctx.createMCPProxy(connectionId);
+    const proxy = await createSiteProxy(await ctx.createMCPProxy(connectionId));
 
     try {
       // Read existing page
diff --git a/packages/starter-template/package.json b/packages/starter-template/package.json
index 3775703fb5..4f6fd94444 100644
--- a/packages/starter-template/package.json
+++ b/packages/starter-template/package.json
@@ -6,7 +6,8 @@
   "scripts": {
     "dev": "react-router dev",
     "build": "react-router build",
-    "preview": "vite preview"
+    "preview": "vite preview",
+    "check": "tsc --noEmit"
   },
   "dependencies": {
     "react": "^19.2.0",