feat: add puck ai plugin

.github/workflows/autogenerate-docs.yml

@@ -47,7 +47,7 @@ jobs:
         id: commit_docs
         uses: EndBug/add-and-commit@v9
         with:
-          add: '["packages/visual-editor/src/docs/components.md", "packages/visual-editor/src/docs/ai/components.d.ts"]'
+          add: '["packages/visual-editor/src/docs/components.md"]'
           message: "docs: auto-generate component documentation"
           push: true
           default_author: github_actions

packages/puck-ai-backend/.gitignore

@@ -0,0 +1,12 @@
+# wrangler project
+
+.dev.vars*
+!.dev.vars.example
+.env*
+!.env.example
+.wrangler/
+
+worker-configuration.d.ts
+
+# IDE
+.vscode/**

packages/puck-ai-backend/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "puck-ai-backend",
+  "version": "0.0.0",
+  "author": "sumo@yext.com",
+  "private": true,
+  "packageManager": "pnpm@9.12.3",
+  "scripts": {
+    "deploy": "wrangler deploy",
+    "dev": "wrangler dev",
+    "start": "wrangler dev",
+    "cf-typegen": "wrangler types"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.1",
+    "typescript": "^5.5.2",
+    "wrangler": "^4.63.0"
+  },
+  "dependencies": {
+    "@puckeditor/cloud-client": "0.6.0",
+    "hono": "^4.6.12"
+  }
+}

packages/puck-ai-backend/src/cors.ts

@@ -0,0 +1,53 @@
+import type { MiddlewareHandler } from "hono";
+
+const isLocalHost = (host: string) =>
+  host === "localhost" || host === "127.0.0.1" || host === "0.0.0.0";
+
+const isAllowedOrigin = (origin: string, isLocalServer: boolean) => {
+  try {
+    const url = new URL(origin);
+    const host = url.hostname.toLowerCase();
+    if (host.endsWith(".preview.pagescdn.com")) {
+      return true;
+    }
+    if (isLocalServer && isLocalHost(host)) {
+      return true;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+};
+
+export const corsForPuck: MiddlewareHandler = async (c, next) => {
+  const origin = c.req.header("Origin");
+  const hostHeader = c.req.header("Host") ?? "";
+  const requestHost = hostHeader.split(":")[0].toLowerCase();
+  const isLocalServer = isLocalHost(requestHost);
+  const allowed = origin ? isAllowedOrigin(origin, isLocalServer) : false;
+
+  if (c.req.method === "OPTIONS") {
+    if (allowed && origin) {
+      c.header("Access-Control-Allow-Origin", origin);
+      c.header("Vary", "Origin");
+      c.header("Access-Control-Allow-Methods", "POST, OPTIONS");
+      const requestedHeaders = c.req.header("Access-Control-Request-Headers");
+      if (requestedHeaders) {
+        c.header("Access-Control-Allow-Headers", requestedHeaders);
+      }
+    }
+    return c.body(null, 204);
+  }
+
+  await next();
+
+  if (allowed && origin) {
+    c.res.headers.set("Access-Control-Allow-Origin", origin);
+    c.res.headers.set("Vary", "Origin");
+    c.res.headers.set("Access-Control-Allow-Methods", "POST, OPTIONS");
+    const requestedHeaders = c.req.header("Access-Control-Request-Headers");
+    if (requestedHeaders) {
+      c.res.headers.set("Access-Control-Allow-Headers", requestedHeaders);
+    }
+  }
+};

packages/puck-ai-backend/src/index.ts

@@ -0,0 +1,12 @@
+import { Hono } from "hono";
+import { corsForPuck } from "./cors";
+import { puckRouter } from "./puckRouter";
+
+const app = new Hono();
+
+app.get("/", (c) => c.text("Yext Pages Puck AI Backend is running."));
+
+app.use("/api/puck/*", corsForPuck);
+app.post("/api/puck/:route", puckRouter);
+
+export default app;

packages/puck-ai-backend/src/puckRouter.ts

@@ -0,0 +1,87 @@
+import { puckHandler, ChatParams } from "@puckeditor/cloud-client";
+import type { Context } from "hono";
+
+type CustomChatParams = ChatParams & { systemPrompt: string };
+
+const parseBody = async (c: Context): Promise<CustomChatParams | undefined> => {
+  const contentType = c.req.header("content-type") ?? "";
+  if (contentType.includes("application/json")) {
+    try {
+      return await c.req.json();
+    } catch {
+      return;
+    }
+  }
+  if (
+    contentType.includes("application/x-www-form-urlencoded") ||
+    contentType.includes("multipart/form-data")
+  ) {
+    try {
+      const parsedBody = await c.req.parseBody();
+      if (typeof parsedBody === "object" && "chatId" in parsedBody) {
+        return parsedBody as unknown as CustomChatParams;
+      }
+      return;
+    } catch {
+      return;
+    }
+  }
+  return;
+};
+
+/** Accept the request from the editor, forward it to Puck, and stream the response. */
+export const puckRouter = async (c: Context) => {
+  try {
+    const puckApiKey = c.env.PUCK_API_KEY;
+    if (!puckApiKey) {
+      return c.json({ success: false, error: "Missing PUCK_API_KEY" }, 500);
+    }
+
+    const origin = c.req.header("Origin");
+    if (!origin) {
+      return c.json({ success: false, error: "Missing Origin header" }, 400);
+    }
+    const pathname = `/api/puck/${c.req.param("route") ?? ""}`.replace(
+      /\/+$/,
+      "",
+    );
+    const url = new URL(pathname, origin);
+
+    const body = await parseBody(c);
+
+    if (!body) {
+      return c.json({ success: false, error: "Invalid request body" }, 400);
+    }
+
+    const puckRequest = new Request(url, {
+      method: "POST",
+      body: JSON.stringify(body),
+      headers: { "content-type": "application/json" },
+    });
+
+    const puckResponse = await puckHandler(puckRequest, {
+      ai: { context: body.systemPrompt },
+      apiKey: puckApiKey,
+    });
+
+    const isServerSideEvents = (
+      puckResponse.headers.get("content-type") ?? ""
+    ).includes("text/event-stream");
+    if (!isServerSideEvents) {
+      return puckResponse;
+    }
+
+    const headers = new Headers(puckResponse.headers);
+    headers.set("Cache-Control", "no-cache");
+    headers.set("Connection", "keep-alive");
+
+    return new Response(puckResponse.body, {
+      status: puckResponse.status,
+      statusText: puckResponse.statusText,
+      headers,
+    });
+  } catch (error) {
+    console.error(error);
+    return c.json({ success: false, error: "Failed to process request" }, 500);
+  }
+};

packages/puck-ai-backend/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "es2024",
+    "lib": ["es2024"],
+    "jsx": "react-jsx",
+    "module": "es2022",
+    "moduleResolution": "Bundler",
+    "resolveJsonModule": true,
+    "allowJs": true,
+    "checkJs": false,
+    "noEmit": true,
+    "isolatedModules": true,
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["./worker-configuration.d.ts", "node"]
+  },
+  "include": ["worker-configuration.d.ts", "src/**/*.ts"]
+}

packages/puck-ai-backend/wrangler.jsonc

@@ -0,0 +1,14 @@
+/**
+ * For more details on how to configure Wrangler, refer to:
+ * https://developers.cloudflare.com/workers/wrangler/configuration/
+ */
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "puck-ai-backend",
+  "main": "src/index.ts",
+  "compatibility_date": "2025-09-27",
+  "observability": {
+    "enabled": true,
+  },
+  "compatibility_flags": ["nodejs_compat"],
+}

packages/visual-editor/THIRD-PARTY-NOTICES

@@ -1161,12 +1161,11 @@ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
 -----------
 
-The following npm packages may be included in this product:
+The following npm package may be included in this product:
 
- - @puckeditor/core@0.21.1
  - next-themes@0.3.0
 
-These packages each contain the following license:
+This package contains the following license:
 
 MIT
 

packages/visual-editor/package.json

@@ -21,6 +21,11 @@
       "import": "./dist/visual-editor.js",
       "default": "./dist/visual-editor.js"
     },
+    "./tailwind": {
+      "types": "./dist/tailwind.d.ts",
+      "import": "./dist/tailwind.js",
+      "default": "./dist/tailwind.js"
+    },
     "./plugin": {
       "import": "./dist/plugin/plugin.js",
       "default": "./dist/plugin/plugin.js"
@@ -42,7 +47,7 @@
     "autofix": "pnpm run lint && pnpm run prettier",
     "prepare": "pnpm build",
     "generate-notices": "generate-license-file --input package.json --output ./THIRD-PARTY-NOTICES --overwrite",
-    "generate-component-docs": "api-extractor run --local ; node generate-docs.mjs ; tsx scripts/generateComponentTypeDefinitions.ts",
+    "generate-component-docs": "api-extractor run --local ; node generate-docs.mjs",
     "docs:dev": "vitepress dev .",
     "docs:build": "vitepress build .",
     "docs:preview": "vitepress preview .",
@@ -62,7 +67,6 @@
     "@microsoft/api-documenter": "^7.26.29",
     "@microsoft/api-extractor": "^7.52.8",
     "@microsoft/api-extractor-model": "^7.30.6",
-    "@puckeditor/core": "0.21.1",
     "@radix-ui/react-accordion": "^1.2.3",
     "@radix-ui/react-alert-dialog": "^1.1.1",
     "@radix-ui/react-dialog": "^1.1.13",
@@ -163,6 +167,8 @@
     "@yext/search-ui-react": "^2.0.2",
     "mapbox-gl": "^2.9.2",
     "react": "^17.0.2 || ^18.2.0",
-    "react-dom": "^17.0.2 || ^18.2.0"
+    "react-dom": "^17.0.2 || ^18.2.0",
+    "@puckeditor/core": "0.21.1",
+    "@puckeditor/plugin-ai": "0.6.0"
   }
 }