@pantheon-systems/create-p1-starter-kit 0.5.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pantheon-systems/create-p1-starter-kit",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Scaffold a new P1 starter project",
   "type": "module",
   "bin": {
@@ -33,7 +33,9 @@
     "node": ">=20.12.0"
   },
   "devDependencies": {
-    "vitest": "^4.1.5"
+    "vitest": "^4.1.5",
+    "@pantheon-systems/css-client": "0.7.0",
+    "@pantheon-systems/puck-css": "0.7.0"
   },
   "dependencies": {
     "@clack/prompts": "^1.5.1",

package/template/.env.example

@@ -19,3 +19,9 @@ CSS_API_KEY=your-api-key
 # Show the RoleSwitcher dropdown in the P1 editor for local testing of
 # admin/editor/junior-editor permissions. Never enable this in production.
 # NEXT_PUBLIC_ENABLE_ROLE_SWITCHER=true
+
+# --- AI chatbot (optional) ---
+# LaunchDarkly client-side ID used to evaluate the `p1-chatbot` flag. It is
+# public by design (safe to expose in the browser). When unset, the chatbot
+# stays hidden.
+# NEXT_PUBLIC_LD_CLIENT_ID=your-launchdarkly-client-side-id

package/template/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @pantheon-systems/p1-starter
 
+## 1.0.6
+
+### Patch Changes
+
+- Updated dependencies [b0254ff]
+- Updated dependencies
+- Updated dependencies [e937842]
+- Updated dependencies [e937842]
+  - @pantheon-systems/puck-css@0.7.0
+  - @pantheon-systems/css-client@0.7.0
+  - @pantheon-systems/p1-next-sdk@0.7.0
+
+## 1.0.5
+
+### Patch Changes
+
+- @pantheon-systems/puck-css@0.6.0
+- @pantheon-systems/p1-next-sdk@0.6.0
+
 ## 1.0.4
 
 ### Patch Changes

package/template/__tests__/chatbot-flag-gate.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+import { shouldShowChatbot, CHATBOT_FLAG_KEY } from "../lib/chatbot-flag/feature-gate";
+
+describe("shouldShowChatbot", () => {
+  it("is off when the flag is disabled, even with an agent URL", () => {
+    expect(shouldShowChatbot(false, "https://agent.example")).toBe(false);
+  });
+
+  it("is off when the agent URL is missing, even with the flag enabled", () => {
+    expect(shouldShowChatbot(true, undefined)).toBe(false);
+    expect(shouldShowChatbot(true, "")).toBe(false);
+  });
+
+  it("is on only when the flag is enabled AND the agent URL is set", () => {
+    expect(shouldShowChatbot(true, "https://agent.example")).toBe(true);
+  });
+
+  it("defaults off when the flag value is undefined (LD not yet resolved / offline)", () => {
+    expect(shouldShowChatbot(undefined, "https://agent.example")).toBe(false);
+  });
+
+  it("exposes the p1-chatbot flag key", () => {
+    expect(CHATBOT_FLAG_KEY).toBe("p1-chatbot");
+  });
+});

package/template/__tests__/chatbot-flag-wiring.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "fs";
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const appDir = resolve(__dirname, "..");
+
+describe("editor-client gates the chatbot behind the p1-chatbot flag", () => {
+  const content = readFileSync(
+    resolve(appDir, "app/p1/[[...p1]]/editor-client.tsx"),
+    "utf-8",
+  );
+
+  it("reads LaunchDarkly flags via useFlags", () => {
+    expect(content).toContain("useFlags");
+  });
+
+  it("gates the AI plugin through shouldShowChatbot", () => {
+    expect(content).toContain("shouldShowChatbot");
+  });
+
+  it("wraps the editor in the chatbot flag provider", () => {
+    expect(content).toContain("ChatbotFlagProvider");
+  });
+
+  it("imports the plugin from the published @pantheon-systems/p1-ai-chat package", () => {
+    expect(content).toContain("@pantheon-systems/p1-ai-chat");
+  });
+});
+
+describe("chatbot flag provider is a client-side LaunchDarkly gate", () => {
+  const content = readFileSync(
+    resolve(appDir, "components/ChatbotFlagProvider.tsx"),
+    "utf-8",
+  );
+
+  it("initializes from the public client-side ID env var", () => {
+    expect(content).toContain("NEXT_PUBLIC_LD_CLIENT_ID");
+  });
+
+  it("uses the launchdarkly-react-client-sdk", () => {
+    expect(content).toContain("launchdarkly-react-client-sdk");
+  });
+});

package/template/app/p1/[[...p1]]/editor-client.tsx

@@ -14,14 +14,19 @@ import {
   editorPathHref,
 } from "@pantheon-systems/puck-css";
 import { P1NextRouterProvider } from "@pantheon-systems/p1-next-sdk";
+import { createAIChatPlugin } from "@pantheon-systems/p1-ai-chat";
+import { useFlags } from "launchdarkly-react-client-sdk";
 import type { Checkpoint } from "@pantheon-systems/puck-css";
 import type { ContentRole } from "@pantheon-systems/puck-css";
+import { P1_ASSETS } from "../../../constants/assets";
 
 import "@pantheon-systems/puck-css/styles.css";
 import "@pantheon-systems/puck-css/pds/styles.css";
 
+import { ChatbotFlagProvider } from "../../../components/ChatbotFlagProvider";
 import { P1Lockup } from "../../../components/p1-lockup";
 import config from "../../../puck.config";
+import { shouldShowChatbot, CHATBOT_FLAG_KEY } from "../../../lib/chatbot-flag/feature-gate";
 
 const DEFAULT_PAGE_DATA = {
   root: { props: { title: "New page" } },
@@ -128,7 +133,9 @@ export function EditorClientWrapper({ path }: { path: string }) {
           config={{ ...p1Config, userRole }}
           loginFallback={<P1SignInPage />}
         >
-          <EditorContent path={path} lastGoodStateRef={lastGoodStateRef} />
+          <ChatbotFlagProvider>
+            <EditorContent path={path} lastGoodStateRef={lastGoodStateRef} />
+          </ChatbotFlagProvider>
         </P1App>
         {process.env.NEXT_PUBLIC_ENABLE_ROLE_SWITCHER === 'true' && (
           <RoleSwitcher currentRole={userRole} onRoleChange={setUserRole} />
@@ -198,6 +205,20 @@ function EditorContent({
   const router = useRouter();
   const { getToken } = useP1Auth();
   const p1Plugins = useP1Plugins(path, config);
+  const flags = useFlags();
+  const agentUrl = process.env.NEXT_PUBLIC_AGENT_URL;
+  const chatbotEnabled = shouldShowChatbot(flags[CHATBOT_FLAG_KEY], agentUrl);
+  const aiPlugin = React.useMemo(
+    () =>
+      chatbotEnabled && agentUrl
+        ? createAIChatPlugin({ agentUrl })
+        : null,
+    [chatbotEnabled, agentUrl],
+  );
+  const additionalPlugins = React.useMemo(
+    () => (aiPlugin ? [...p1Plugins, aiPlugin] : p1Plugins),
+    [p1Plugins, aiPlugin],
+  ) as typeof p1Plugins;
 
   const [redirecting, setRedirecting] = React.useState(false);
 
@@ -236,13 +257,14 @@ function EditorContent({
   const { loading, error, puckKey, puckProps } = useP1Editor({
     documentPath: path,
     puckConfig: editorConfig,
-    additionalPlugins: p1Plugins,
+    additionalPlugins,
     onDocumentNotFound: handleDocumentNotFound,
     pluginOptions: {
       onDocumentSelect: handleDocumentSelect,
       selectedDocumentPath: path,
       siteId: process.env.NEXT_PUBLIC_CSS_SITE_ID,
       dashboardUrl: process.env.NEXT_PUBLIC_P1_ADMIN_DASHBOARD_URL,
+      logoUrl: P1_ASSETS.LOGO_URL,
     },
     overrideOptions: {
       showDefaultPublish: false,
@@ -337,7 +359,7 @@ function EditorContent({
         </div>
       )}
       {/* eslint-disable-next-line @typescript-eslint/no-explicit-any */}
-      <Puck key={displayState.puckKey} {...displayState.puckProps as any} _experimentalFullScreenCanvas={true} />
+      <Puck key={`${displayState.puckKey}-${chatbotEnabled ? "ai" : "no-ai"}`} {...displayState.puckProps as any} _experimentalFullScreenCanvas={true} />
     </div>
   );
 }

package/template/ci-examples/github-actions-sync-puck-registry.yml

@@ -0,0 +1,51 @@
+# Optional: syncs this site's Puck component registry to the CSS backend
+# headlessly on every push, without anyone needing to open the editor.
+#
+# This file is NOT active until you copy it into .github/workflows/ yourself
+# — it deliberately lives outside that directory in the scaffolded project so
+# it can never auto-run before you've provisioned secrets.
+#
+# Setup:
+#   1. Create a sat_ site token scoped to write:registry ONLY (do not reuse
+#      your read-scoped P1_CSS_API_KEY / SSR token for this).
+#   2. Add repo secrets: CSS_BASE_URL, CSS_SITE_ID, CSS_REGISTRY_API_KEY.
+#   3. Copy this file to .github/workflows/sync-puck-registry.yml.
+#
+# Triggers on push to any branch that touches puck.config.tsx or
+# components/puck/** — the sync script resolves the CSS branch by matching
+# the pushed git branch's name (falling back to the site's main branch when
+# no CSS_BRANCH_ID is given). A push on a branch with no matching CSS branch
+# is not an error: the script logs a skip and exits 0.
+name: Sync Puck Component Registry
+
+on:
+  push:
+    branches:
+      - '**'
+    paths:
+      - 'puck.config.tsx'
+      - 'components/puck/**'
+  workflow_dispatch:
+    inputs:
+      branch_id:
+        description: 'CSS branch ID/name to sync against (blank = match the current git branch, else site main)'
+        required: false
+        default: ''
+
+jobs:
+  sync-registry:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: npm
+      - run: npm ci
+      - name: Sync component registry
+        run: npm run sync:registry
+        env:
+          CSS_BASE_URL: ${{ secrets.CSS_BASE_URL }}
+          CSS_SITE_ID: ${{ secrets.CSS_SITE_ID }}
+          CSS_REGISTRY_API_KEY: ${{ secrets.CSS_REGISTRY_API_KEY }}
+          CSS_BRANCH_ID: ${{ github.event.inputs.branch_id || github.ref_name }}

package/template/components/ChatbotFlagProvider.tsx

@@ -0,0 +1,49 @@
+"use client";
+
+import React from "react";
+import { LDProvider } from "launchdarkly-react-client-sdk";
+import { useP1Auth } from "@pantheon-systems/puck-css";
+
+/**
+ * Wraps the editor with a LaunchDarkly client-side provider so the `p1-chatbot`
+ * flag can be evaluated at runtime. The client-side ID is public by design.
+ *
+ * When NEXT_PUBLIC_LD_CLIENT_ID is unset (local dev / offline), LaunchDarkly is
+ * not initialized and children render without a provider — `useFlags()` then
+ * returns no flags, so the chatbot defaults to hidden.
+ */
+export function ChatbotFlagProvider({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const clientSideID = process.env.NEXT_PUBLIC_LD_CLIENT_ID;
+  const { user } = useP1Auth();
+
+  if (!clientSideID) {
+    return <>{children}</>;
+  }
+
+  // LaunchDarkly evaluates the flag for the context present at mount and does not
+  // re-identify on context change. This provider mounts inside <P1App> (after
+  // auth), so the authenticated user is available here; the anonymous fallback
+  // only applies if it ever renders pre-auth.
+  //
+  // Key on the always-present, stable user id — email is optional on AuthUser, so
+  // keying on it would silently drop emailless users into the anonymous branch and
+  // lose per-user rollout stickiness. (LaunchDarkly also favors a non-PII key.)
+  // Email is kept as a targeting attribute.
+  const context = user
+    ? { kind: "user" as const, key: user.id, email: user.email }
+    : { kind: "user" as const, key: "anonymous", anonymous: true };
+
+  return (
+    <LDProvider
+      clientSideID={clientSideID}
+      context={context}
+      reactOptions={{ useCamelCaseFlagKeys: false }}
+    >
+      {children}
+    </LDProvider>
+  );
+}

package/template/constants/assets.ts

@@ -0,0 +1,3 @@
+export const P1_ASSETS = {
+  LOGO_URL: "/images/p1_logo.svg",
+} as const;

package/template/lib/chatbot-flag/feature-gate.ts

@@ -0,0 +1,17 @@
+/** LaunchDarkly flag that gates the AI chatbot. Short-lived — removed once the
+ *  chatbot ships to everyone in the alpha. */
+export const CHATBOT_FLAG_KEY = "p1-chatbot";
+
+/**
+ * Whether the AI chatbot plugin should be mounted in the editor.
+ *
+ * Requires both the `p1-chatbot` LaunchDarkly flag to be enabled and an agent
+ * URL to be configured. Defaults off when the flag is `undefined` (LD not yet
+ * resolved, unset client ID, or offline), so the chatbot stays hidden by default.
+ */
+export function shouldShowChatbot(
+  flagEnabled: boolean | undefined,
+  agentUrl: string | undefined,
+): boolean {
+  return Boolean(flagEnabled && agentUrl);
+}

package/template/package.json

@@ -7,15 +7,20 @@
     "build": "next build",
     "start": "next start",
     "test": "vitest run",
-    "lint": "eslint ."
+    "lint": "eslint .",
+    "sync:registry": "tsx scripts/sync-puck-registry.ts"
   },
   "dependencies": {
     "@pantheon-systems/cpub-react-sdk": "^5.2.1",
-    "@pantheon-systems/p1-next-sdk": "^0.5.0",
-    "@pantheon-systems/puck-css": "^0.5.0",
+    "@pantheon-systems/css-client": "^0.7.0",
+    "@pantheon-systems/p1-ai-chat": "^0.1.0",
+    "@pantheon-systems/p1-next-sdk": "^0.7.0",
+    "@pantheon-systems/pds-toolkit-react": "2.0.0-alpha.44",
+    "@pantheon-systems/puck-css": "^0.7.0",
     "@puckeditor/core": "^0.21.1",
     "@tailwindcss/postcss": "^4.2.2",
     "classnames": "^2.5.1",
+    "launchdarkly-react-client-sdk": "^3.9.2",
     "next": "^16.2.6",
     "postcss": "^8.5.12",
     "react": "^19.2.5",
@@ -28,6 +33,7 @@
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "eslint": "^9.27.0",
+    "tsx": "^4.23.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.5",
     "@eslint/js": "^9.27.0",

package/template/public/images/p1_logo.svg

@@ -0,0 +1,12 @@
+<svg width="40" height="33" viewBox="0 0 40 33" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M1.47059 0L4.41354 7.08983H0.667969L1.8719 10.1666H9.49682L1.47059 0Z" fill="#FFDC28"/>
+<path d="M11.4372 25.7508L10.1664 22.6741H8.42739L4.81559 13.9121H3.27723L6.88903 22.6741H2.47461L10.6346 32.8406L7.69166 25.7508H11.4372Z" fill="#FFDC28"/>
+<path d="M12.4403 19.5305H7.69141L8.69468 21.9384H12.4403C12.5071 21.9384 12.7747 21.8046 12.7747 20.7345C12.7078 19.6643 12.5071 19.5305 12.4403 19.5305Z" fill="#23232D"/>
+<path d="M12.9088 16.6543H6.55469L7.55797 19.0622H12.9088C12.9757 19.0622 13.2432 18.9284 13.2432 17.8582C13.1763 16.7881 12.9757 16.6543 12.9088 16.6543Z" fill="#23232D"/>
+<path d="M12.4397 13.3102C12.5066 13.3102 12.7741 13.1764 12.7741 12.1063C12.7741 11.0361 12.5735 10.9023 12.4397 10.9023H7.22266L8.22593 13.3102H12.4397Z" fill="#23232D"/>
+<path d="M9.36461 16.1862H12.8426C12.9095 16.1862 13.1771 16.0524 13.1771 14.9823C13.1771 13.9121 12.9764 13.7783 12.8426 13.7783H8.36133L9.36461 16.1862Z" fill="#23232D"/>
+<path d="M12.4403 19.5305H7.69141L8.69468 21.9384H12.4403C12.5071 21.9384 12.7747 21.8046 12.7747 20.7345C12.7078 19.6643 12.5071 19.5305 12.4403 19.5305Z" fill="#23232D"/>
+<path d="M12.9088 16.6545H6.55469L7.55797 19.0624H12.9088C12.9757 19.0624 13.2432 18.9286 13.2432 17.8585C13.1763 16.7883 12.9757 16.6545 12.9088 16.6545Z" fill="#23232D"/>
+<path d="M3.6118 16.1863L2.47475 13.3102H5.08328L6.28721 16.1863H8.76196L6.55475 10.9023H1.13705C0.735737 10.9023 0.468196 10.9023 0.267541 11.5043C0.066885 12.24 0 13.6446 0 16.3869C0 19.1292 -2.59134e-07 20.5338 0.267541 21.2696C0.468196 21.8715 0.668852 21.8715 1.13705 21.8715H5.8859L3.6118 16.1863Z" fill="#23232D"/>
+<path d="M21.0527 23.9409V9.39014H26.5117C27.6315 9.39014 28.569 9.59847 29.3242 10.0151C30.0859 10.4318 30.6621 11.0047 31.0527 11.7339C31.4434 12.4631 31.6387 13.2899 31.6387 14.2144C31.6387 15.1453 31.4401 15.9754 31.043 16.7046C30.6523 17.4272 30.0729 17.9969 29.3047 18.4136C28.5365 18.8237 27.5924 19.0288 26.4727 19.0288H22.8594V16.8608H26.1113C26.7689 16.8608 27.306 16.7502 27.7227 16.5288C28.1458 16.3009 28.4551 15.9884 28.6504 15.5913C28.8522 15.1877 28.9531 14.7287 28.9531 14.2144C28.9531 13.6935 28.8522 13.2378 28.6504 12.8472C28.4551 12.45 28.1458 12.144 27.7227 11.9292C27.306 11.7078 26.7656 11.5972 26.1016 11.5972H23.6895V23.9409H21.0527ZM38.7676 9.39014V23.9409H36.1504V11.9585H36.0625L32.6641 14.1362V11.7144L36.2773 9.39014H38.7676Z" fill="#23232D"/>
+</svg>

package/template/scripts/__tests__/asset-stub-hooks.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it, vi } from "vitest";
+import { resolve, load } from "../asset-stub-hooks.mjs";
+
+describe("resolve", () => {
+  it("short-circuits CSS imports to an asset-stub URL without calling nextResolve", async () => {
+    const nextResolve = vi.fn();
+    const result = await resolve("./styles.css", {}, nextResolve);
+    expect(result.shortCircuit).toBe(true);
+    expect(result.url.startsWith("asset-stub:")).toBe(true);
+    expect(nextResolve).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    "./logo.png", "./photo.jpg", "./photo.jpeg", "./icon.svg", "./anim.gif",
+    "./banner.webp", "./favicon.ico", "./sprite.bmp", "./photo.avif",
+    "./font.woff", "./font.woff2", "./font.ttf", "./font.eot", "./font.otf",
+    "./clip.mp4", "./clip.webm", "./clip.mov", "./audio.mp3", "./audio.wav",
+    "./theme.scss", "./theme.sass", "./theme.less",
+  ])("short-circuits %s", async (specifier) => {
+    const nextResolve = vi.fn();
+    const result = await resolve(specifier, {}, nextResolve);
+    expect(result.shortCircuit).toBe(true);
+    expect(nextResolve).not.toHaveBeenCalled();
+  });
+
+  it("passes .ts specifiers through to nextResolve unchanged", async () => {
+    const nextResolve = vi.fn().mockResolvedValue({ url: "file:///abs/path.ts", shortCircuit: true });
+    const result = await resolve("./puck.config.tsx", {}, nextResolve);
+    expect(nextResolve).toHaveBeenCalledWith("./puck.config.tsx", {});
+    expect(result.url).toBe("file:///abs/path.ts");
+  });
+
+  it("passes bare package specifiers through to nextResolve unchanged", async () => {
+    const nextResolve = vi.fn().mockResolvedValue({ url: "file:///node_modules/react/index.js", shortCircuit: true });
+    await resolve("react", {}, nextResolve);
+    expect(nextResolve).toHaveBeenCalledWith("react", {});
+  });
+
+  it("propagates a real module-resolution error from nextResolve instead of masking it", async () => {
+    const nextResolve = vi.fn().mockRejectedValue(new Error("Cannot find module"));
+    await expect(resolve("./missing-module", {}, nextResolve)).rejects.toThrow("Cannot find module");
+  });
+});
+
+describe("load", () => {
+  it("returns an empty default export for asset-stub URLs without calling nextLoad", async () => {
+    const nextLoad = vi.fn();
+    const result = await load("asset-stub:.%2Fstyles.css", {}, nextLoad);
+    expect(result).toEqual({ format: "module", source: "export default {};", shortCircuit: true });
+    expect(nextLoad).not.toHaveBeenCalled();
+  });
+
+  it("passes non-asset-stub URLs through to nextLoad unchanged", async () => {
+    const nextLoad = vi.fn().mockResolvedValue({ format: "module", source: "export default 1;", shortCircuit: true });
+    const result = await load("file:///abs/path.ts", {}, nextLoad);
+    expect(nextLoad).toHaveBeenCalledWith("file:///abs/path.ts", {});
+    expect(result.source).toBe("export default 1;");
+  });
+
+  it("propagates a real load error from nextLoad instead of masking it", async () => {
+    const nextLoad = vi.fn().mockRejectedValue(new Error("Syntax error"));
+    await expect(load("file:///abs/broken.ts", {}, nextLoad)).rejects.toThrow("Syntax error");
+  });
+});

package/template/scripts/__tests__/sync-puck-registry.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from "vitest";
+import { validateEnv, resolveConfigModule, resolveBranchId, NoBranchMatchError } from "../sync-puck-registry.js";
+
+function baseEnv(overrides: Record<string, string | undefined> = {}): Record<string, string | undefined> {
+  return {
+    CSS_BASE_URL: "https://css.example.com",
+    CSS_SITE_ID: "site-123",
+    CSS_REGISTRY_API_KEY: "sat_registrytoken",
+    ...overrides,
+  };
+}
+
+describe("validateEnv", () => {
+  it("accepts CSS_BASE_URL/CSS_SITE_ID/CSS_REGISTRY_API_KEY directly", () => {
+    const result = validateEnv(baseEnv());
+    expect(result.baseUrl).toBe("https://css.example.com");
+    expect(result.siteId).toBe("site-123");
+    expect(result.apiKey).toBe("sat_registrytoken");
+    expect(result.branchOverride).toBeUndefined();
+    expect(result.puckConfigPath).toBe("puck.config.tsx");
+  });
+
+  it("falls back to NEXT_PUBLIC_CSS_BASE_URL and NEXT_PUBLIC_CSS_SITE_ID", () => {
+    const result = validateEnv(
+      baseEnv({
+        CSS_BASE_URL: undefined,
+        CSS_SITE_ID: undefined,
+        NEXT_PUBLIC_CSS_BASE_URL: "https://fallback.example.com",
+        NEXT_PUBLIC_CSS_SITE_ID: "site-fallback",
+      }),
+    );
+    expect(result.baseUrl).toBe("https://fallback.example.com");
+    expect(result.siteId).toBe("site-fallback");
+  });
+
+  it("falls back to NEXT_PUBLIC_CSS_BRANCH_ID for the branch override", () => {
+    const result = validateEnv(baseEnv({ NEXT_PUBLIC_CSS_BRANCH_ID: "staging" }));
+    expect(result.branchOverride).toBe("staging");
+  });
+
+  it("prefers CSS_BRANCH_ID over the NEXT_PUBLIC_ fallback when both are set", () => {
+    const result = validateEnv(baseEnv({ CSS_BRANCH_ID: "explicit", NEXT_PUBLIC_CSS_BRANCH_ID: "staging" }));
+    expect(result.branchOverride).toBe("explicit");
+  });
+
+  it("defaults PUCK_CONFIG_PATH to puck.config.tsx", () => {
+    const result = validateEnv(baseEnv());
+    expect(result.puckConfigPath).toBe("puck.config.tsx");
+  });
+
+  it("honors an explicit PUCK_CONFIG_PATH", () => {
+    const result = validateEnv(baseEnv({ PUCK_CONFIG_PATH: "config/puck.config.tsx" }));
+    expect(result.puckConfigPath).toBe("config/puck.config.tsx");
+  });
+
+  it("reports all missing required vars together, not just the first", () => {
+    expect(() => validateEnv({})).toThrowError(/CSS_BASE_URL[\s\S]*CSS_SITE_ID[\s\S]*CSS_REGISTRY_API_KEY/);
+  });
+
+  it("gives an explicit, actionable message when only P1_CSS_API_KEY is set (do not reuse the read-only token)", () => {
+    expect(() =>
+      validateEnv(baseEnv({ CSS_REGISTRY_API_KEY: undefined, P1_CSS_API_KEY: "sat_readonlytoken" })),
+    ).toThrowError(/write:registry/);
+  });
+
+  it("does not accidentally accept P1_CSS_API_KEY as a substitute for CSS_REGISTRY_API_KEY", () => {
+    const result = () =>
+      validateEnv(baseEnv({ CSS_REGISTRY_API_KEY: undefined, P1_CSS_API_KEY: "sat_readonlytoken" }));
+    expect(result).toThrow();
+  });
+});
+
+describe("resolveConfigModule", () => {
+  it("prefers a default export", () => {
+    const mod = { default: { components: {} }, config: { wrong: true } };
+    expect(resolveConfigModule(mod)).toBe(mod.default);
+  });
+
+  it("falls back to a named config export when there is no default", () => {
+    const mod = { config: { components: {} } };
+    expect(resolveConfigModule(mod)).toBe(mod.config);
+  });
+
+  it("falls back to the module itself when neither default nor config is present", () => {
+    const mod = { components: {} };
+    expect(resolveConfigModule(mod)).toBe(mod);
+  });
+});
+
+describe("resolveBranchId", () => {
+  const branches = [
+    { id: "b-1", siteId: "site-123", name: "main", isMain: true },
+    { id: "b-2", siteId: "site-123", name: "staging", isMain: false },
+  ];
+
+  it("resolves to the main branch when no override is given", () => {
+    expect(resolveBranchId(branches as never, "site-123")).toBe("b-1");
+  });
+
+  it("resolves an override by branch id", () => {
+    expect(resolveBranchId(branches as never, "site-123", "b-2")).toBe("b-2");
+  });
+
+  it("resolves an override by branch name", () => {
+    expect(resolveBranchId(branches as never, "site-123", "staging")).toBe("b-2");
+  });
+
+  it("throws NoBranchMatchError ('No main branch found') when there is no override and no isMain branch", () => {
+    const noMain = [{ id: "b-2", siteId: "site-123", name: "staging", isMain: false }];
+    expect(() => resolveBranchId(noMain as never, "site-123")).toThrowError(
+      "No main branch found for site site-123",
+    );
+    try {
+      resolveBranchId(noMain as never, "site-123");
+      expect.unreachable();
+    } catch (err) {
+      expect(err).toBeInstanceOf(NoBranchMatchError);
+    }
+  });
+
+  it("throws NoBranchMatchError when an explicit override matches no branch by id or name", () => {
+    expect(() => resolveBranchId(branches as never, "site-123", "nonexistent")).toThrow(NoBranchMatchError);
+  });
+});

package/template/scripts/asset-stub-hooks.mjs

@@ -0,0 +1,34 @@
+/**
+ * Node module customization hooks that stub out non-JS asset imports
+ * (CSS, images, fonts, video) so a plain Node script can `import()` a
+ * Next.js app's puck.config.tsx without a bundler. Zero dependencies.
+ *
+ * Wire in with node:module's register() — not the --import flag, which
+ * does not auto-install a resolve/load-only hooks file.
+ */
+
+const ASSET_EXTENSION_PATTERN =
+  /\.(css|scss|sass|less|png|jpe?g|gif|svg|webp|ico|bmp|avif|woff2?|ttf|eot|otf|mp4|webm|mov|mp3|wav)$/i;
+
+const ASSET_STUB_PROTOCOL = 'asset-stub:';
+
+export async function resolve(specifier, context, nextResolve) {
+  if (ASSET_EXTENSION_PATTERN.test(specifier)) {
+    return {
+      url: `${ASSET_STUB_PROTOCOL}${encodeURIComponent(specifier)}`,
+      shortCircuit: true,
+    };
+  }
+  return nextResolve(specifier, context);
+}
+
+export async function load(url, context, nextLoad) {
+  if (url.startsWith(ASSET_STUB_PROTOCOL)) {
+    return {
+      format: 'module',
+      source: 'export default {};',
+      shortCircuit: true,
+    };
+  }
+  return nextLoad(url, context);
+}

package/template/scripts/sync-puck-registry.ts

@@ -0,0 +1,148 @@
+/**
+ * Syncs this site's Puck component registry (_registry/components/* and the
+ * registry index) headlessly, without opening the editor in a browser.
+ * Intended to run from CI on push to main or a branch whose name matches a
+ * CSS branch, whenever puck.config.tsx or components/puck/** change.
+ *
+ * Usage: tsx scripts/sync-puck-registry.ts [--dry-run]
+ *
+ * Required env vars (see validateEnv below for the full fallback contract):
+ *   CSS_BASE_URL, CSS_SITE_ID, CSS_REGISTRY_API_KEY
+ *
+ * CSS_REGISTRY_API_KEY must be a sat_ site token scoped to write:registry
+ * only — do not reuse a read-scoped token (P1_CSS_API_KEY). Because that
+ * token has no read access at all, every run rewrites every component
+ * descriptor + the registry index unconditionally (no skip-if-unchanged) —
+ * see syncComponentRegistryWriteOnly.
+ */
+
+import { register } from "node:module";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { P1Client } from "@pantheon-systems/css-client";
+import type { Branch } from "@pantheon-systems/css-client";
+import { extractDescriptors, syncComponentRegistryWriteOnly } from "@pantheon-systems/puck-css/registry-sync";
+
+export interface ValidatedEnv {
+  baseUrl: string;
+  siteId: string;
+  apiKey: string;
+  branchOverride?: string;
+  puckConfigPath: string;
+}
+
+export function validateEnv(env: Record<string, string | undefined>): ValidatedEnv {
+  const baseUrl = env.CSS_BASE_URL ?? env.NEXT_PUBLIC_CSS_BASE_URL;
+  const siteId = env.CSS_SITE_ID ?? env.NEXT_PUBLIC_CSS_SITE_ID;
+  const apiKey = env.CSS_REGISTRY_API_KEY;
+  const branchOverride = env.CSS_BRANCH_ID ?? env.NEXT_PUBLIC_CSS_BRANCH_ID;
+  const puckConfigPath = env.PUCK_CONFIG_PATH ?? "puck.config.tsx";
+
+  const missing: string[] = [];
+  if (baseUrl === undefined || baseUrl === "") {
+    missing.push("CSS_BASE_URL (or NEXT_PUBLIC_CSS_BASE_URL)");
+  }
+  if (siteId === undefined || siteId === "") {
+    missing.push("CSS_SITE_ID (or NEXT_PUBLIC_CSS_SITE_ID)");
+  }
+  if (apiKey === undefined || apiKey === "") {
+    if (env.P1_CSS_API_KEY !== undefined && env.P1_CSS_API_KEY !== "") {
+      missing.push(
+        "CSS_REGISTRY_API_KEY — do not reuse P1_CSS_API_KEY (your read-scoped site token); " +
+          "create a separate sat_ token scoped to write:registry",
+      );
+    } else {
+      missing.push("CSS_REGISTRY_API_KEY");
+    }
+  }
+
+  if (missing.length > 0) {
+    throw new Error(`Missing required environment variable(s):\n  - ${missing.join("\n  - ")}`);
+  }
+
+  return {
+    baseUrl: baseUrl as string,
+    siteId: siteId as string,
+    apiKey: apiKey as string,
+    branchOverride,
+    puckConfigPath,
+  };
+}
+
+export function resolveConfigModule(mod: unknown): unknown {
+  const record = mod as Record<string, unknown>;
+  return record.default ?? record.config ?? mod;
+}
+
+/**
+ * Thrown by resolveBranchId when no CSS branch matches. Distinguished from
+ * other errors so callers (main(), a CI trigger firing on every git branch)
+ * can treat "this branch has no CSS counterpart" as a benign no-op rather
+ * than a real sync failure.
+ */
+export class NoBranchMatchError extends Error {}
+
+export function resolveBranchId(branches: Branch[], siteId: string, override?: string): string {
+  if (override !== undefined && override !== "") {
+    const match = branches.find((b) => b.id === override || b.name === override);
+    if (match === undefined) {
+      throw new NoBranchMatchError(`No branch matching "${override}" found for site ${siteId}`);
+    }
+    return match.id;
+  }
+  const mainBranch = branches.find((b) => b.isMain);
+  if (mainBranch === undefined) {
+    throw new NoBranchMatchError("No main branch found for site " + siteId);
+  }
+  return mainBranch.id;
+}
+
+async function main(): Promise<void> {
+  const dryRun = process.argv.includes("--dry-run");
+
+  // Registered here (not at module scope) so importing this file for tests
+  // never installs a process-wide loader hook.
+  register("./asset-stub-hooks.mjs", import.meta.url);
+
+  const { baseUrl, siteId, apiKey, branchOverride, puckConfigPath } = validateEnv(process.env);
+
+  const configUrl = pathToFileURL(path.resolve(process.cwd(), puckConfigPath)).href;
+  const mod: unknown = await import(configUrl);
+  const puckConfig = resolveConfigModule(mod);
+
+  const descriptors = extractDescriptors(puckConfig);
+
+  const client = new P1Client({ baseUrl, apiKey });
+  const branches = await client.branches.list(siteId);
+  const branchId = resolveBranchId(branches, siteId, branchOverride);
+
+  if (dryRun) {
+    console.log(
+      `[sync-puck-registry] Dry run: ${String(descriptors.length)} component descriptor(s) found for site ${siteId}, branch ${branchId}. No writes performed.`,
+    );
+    return;
+  }
+
+  const result = await syncComponentRegistryWriteOnly(client, siteId, branchId, descriptors);
+  console.log(
+    `[sync-puck-registry] Synced site ${siteId}, branch ${branchId}: ` +
+      `wrote ${String(result.total)} component descriptor(s) + registry index`,
+  );
+}
+
+const isMainModule = import.meta.url === pathToFileURL(process.argv[1] ?? "").href;
+if (isMainModule) {
+  main().catch((err: unknown) => {
+    // A CI trigger firing on every git branch push has no way to know ahead
+    // of time which branches have a matching CSS branch — that has to be
+    // discovered at runtime. Treat "no match" as a benign no-op, not a
+    // failure, so unrelated feature-branch pushes don't turn CI red.
+    if (err instanceof NoBranchMatchError) {
+      console.log(`[sync-puck-registry] Skipping: ${err.message}`);
+      return;
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    console.error("[sync-puck-registry] FAILED:", message);
+    process.exitCode = 1;
+  });
+}