@pantheon-systems/create-p1-starter-kit 0.6.0 → 0.8.0

package/template/app/p1/(editor)/layout.tsx

@@ -0,0 +1,13 @@
+import "@puckeditor/core/puck.css";
+import { pages } from "./[[...p1]]/p1-pages";
+
+// The editor renders from this layout, NOT the page. The (editor) group is a
+// static segment, so this layout survives navigation between /p1/<pageA> and
+// /p1/<pageB> — a layout inside [[...p1]] would remount on every switch, since
+// Next keys segment cache nodes by param value.
+//
+// Scoping the layout to the (editor) group (instead of app/p1/layout.tsx) is
+// what keeps the editor off sibling routes: /p1/merge and future pages like
+// /p1/settings live outside the group and never render the editor. Add such
+// pages as siblings of (editor), not inside it.
+export default pages.Layout;

package/template/app/page.tsx

@@ -1,14 +1,14 @@
-import { WelcomeBlockRender } from "../components/puck/welcome-block-render";
 import {
   ensureInitialized,
   getPage,
   listRouteTemplateKeysFromDatabase,
   resolveDataTemplates,
-  resolveStringTemplates,
   extractReferencedDatasourceIds,
   loadRemoteDatasourceContext,
 } from "@pantheon-systems/puck-css/server";
 import type { Metadata } from "next";
+import { WelcomeBlockRender } from "../components/puck/welcome-block-render";
+import { resolvePageMetadata } from "../lib/page-seo";
 import { REMOTE_DATASOURCE_FETCHERS } from "../lib/remote-datasource-fetchers";
 import { Client } from "./[...puckPath]/client";
 
@@ -27,25 +27,7 @@ export async function generateMetadata(): Promise<Metadata> {
   if (!pageData) {
     return { title: "P1 Starter Kit" };
   }
-
-  const rawTitle = pageData.root.props?.title;
-  if (typeof rawTitle !== "string") {
-    return { title: rawTitle };
-  }
-  if (!rawTitle.includes("{{")) {
-    return { title: rawTitle };
-  }
-  const routeTemplateKeys = await listRouteTemplateKeysFromDatabase();
-  const referencedDatasourceIds = extractReferencedDatasourceIds(pageData);
-  const context = await loadRemoteDatasourceContext({
-    searchParams: {},
-    fetchImpl: fetch,
-    pagePath: "/",
-    routeTemplateKeys,
-    builtinFetchers: REMOTE_DATASOURCE_FETCHERS,
-    referencedDatasourceIds,
-  });
-  return { title: await resolveStringTemplates(rawTitle, context) };
+  return resolvePageMetadata({ pageData, path: "/", searchParams: {} });
 }
 
 export default async function HomePage() {

package/template/app/styles.css

@@ -1,4 +1,5 @@
 @import "tailwindcss";
+@plugin "@tailwindcss/typography";
 
 body {
   margin: 0;

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

@@ -0,0 +1,57 @@
+# 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 from the pushed
+# git branch's name: the repo's default branch always targets the site's main
+# CSS branch (whatever the git branch is called), any other ref matches a CSS
+# branch by name. A push on a non-default branch with no matching CSS branch
+# is not an error: the script logs a skip and exits 0.
+#
+# CSS_DEFAULT_BRANCH defaults to "main" if omitted — repos whose default
+# branch has another name (master, trunk) need the line below (or must set
+# the variable themselves) for default-branch pushes to sync at all.
+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 }}
+          CSS_DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}

package/template/components/puck/media-figure-block.tsx

@@ -0,0 +1,12 @@
+import { createMediaFigureBlock } from "@pantheon-systems/p1-media/server";
+import { blockPaddingClass } from "./block-padding";
+
+// CDN origin, not the Worker API URL; defaults to production when unset.
+const MEDIA_BASE = process.env.NEXT_PUBLIC_MEDIA_BASE_URL;
+
+export const mediaFigureBlock = createMediaFigureBlock({
+  mediaBaseUrl: MEDIA_BASE,
+  transform: { width: 1200, height: 630, format: "webp" },
+  className: `m-0 ${blockPaddingClass} [&>img]:block [&>img]:h-auto [&>img]:max-h-[400px] [&>img]:w-full [&>img]:max-w-4xl [&>img]:rounded-lg [&>img]:object-contain`,
+  captionClassName: "mt-3 max-w-4xl text-sm text-neutral-600",
+});

package/template/components/puck/paragraph-block.tsx

@@ -1,21 +1,13 @@
-import { isValidElement, type ReactNode } from "react";
+"use client";
+import { type ReactNode, isValidElement } from "react";
+import { richtextField } from "@pantheon-systems/puck-css/fields";
 import { blockPaddingClass } from "./block-padding";
-import ReactMarkdown from "react-markdown";
-
-function asMarkdownText(value: unknown): string {
-  if (typeof value === "string") return value;
-  if (typeof value === "number" || typeof value === "boolean") return String(value);
-  return "";
-}
+import { sanitizeRichtextHtml } from "./sanitize-richtext";
 
 export const paragraphBlock = {
   label: "Paragraph",
   fields: {
-    text: {
-      type: "textarea" as const,
-      label: "Text",
-      contentEditable: true,
-    },
+    text: richtextField,
   },
   defaultProps: {
     text: "Add your copy here. You can use multiple lines.",
@@ -24,25 +16,13 @@ export const paragraphBlock = {
     if (isValidElement(text)) {
       return <div className={blockPaddingClass}>{text}</div>;
     }
-    const markdown = asMarkdownText(text);
     return (
-      <div className={blockPaddingClass}>
-        <ReactMarkdown
-          components={{
-            p: ({ children }) => <p className="m-0 max-w-prose leading-relaxed">{children}</p>,
-            a: ({ href, children }) => (
-              <a
-                href={href}
-                className="text-blue-700 underline decoration-blue-700/40 underline-offset-2 hover:decoration-blue-700"
-              >
-                {children}
-              </a>
-            ),
-          }}
-        >
-          {markdown}
-        </ReactMarkdown>
-      </div>
+      <div
+        className={`${blockPaddingClass} prose max-w-prose`}
+        dangerouslySetInnerHTML={{
+          __html: typeof text === "string" ? sanitizeRichtextHtml(text) : "",
+        }}
+      />
     );
   },
 };

package/template/components/puck/sanitize-richtext.ts

@@ -0,0 +1,44 @@
+import DOMPurify from "isomorphic-dompurify";
+
+/**
+ * Sanitize richtext HTML before it is rendered via `dangerouslySetInnerHTML`.
+ *
+ * Blocks render editor-authored richtext as an HTML string on the public,
+ * server-rendered surface. This is defense-in-depth at the render boundary:
+ * it does not rely on the richtext editor's schema or on TipTap's default
+ * link-protocol allowlist to be the only thing standing between stored content
+ * and the DOM. The allowlist below matches what the richtext toolbar can
+ * actually produce (inline formatting + lists + links); anything else —
+ * `<script>`, `<img onerror>`, `javascript:`/`data:` hrefs — is stripped.
+ *
+ * Runs in both Node (SSR) and the browser via isomorphic-dompurify.
+ */
+const ALLOWED_TAGS = [
+  "p",
+  "br",
+  "strong",
+  "b",
+  "em",
+  "i",
+  "u",
+  "s",
+  "ul",
+  "ol",
+  "li",
+  "a",
+  "code",
+  "span",
+];
+
+const ALLOWED_ATTR = ["href", "target", "rel"];
+
+export function sanitizeRichtextHtml(html: string): string {
+  return DOMPurify.sanitize(html, {
+    ALLOWED_TAGS,
+    ALLOWED_ATTR,
+    // Explicit protocol allowlist (defense-in-depth over DOMPurify's default,
+    // which already rejects javascript:/unknown schemes): only safe link
+    // protocols, plus relative/anchor hrefs.
+    ALLOWED_URI_REGEXP: /^(?:https?:|mailto:|tel:|ftp:|#|\/|\.)/i,
+  });
+}

package/template/lib/page-seo.ts

@@ -0,0 +1,79 @@
+import type { Metadata } from "next";
+import type {
+  SeoMetadata,
+  getPage,
+} from "@pantheon-systems/puck-css/server";
+import {
+  loadRemoteDatasourceContext,
+  extractReferencedDatasourceIds,
+  listRouteTemplateKeysFromDatabase,
+  resolveStringTemplates,
+} from "@pantheon-systems/puck-css/server";
+import { REMOTE_DATASOURCE_FETCHERS } from "./remote-datasource-fetchers";
+import { buildPageMetadata } from "./seo-metadata";
+
+type PageData = Awaited<ReturnType<typeof getPage>>;
+
+// Untitled pages carry the editor's defaultProps.title boilerplate
+// (components/puck/root.tsx); never ship it as <title>/og:title.
+const DEFAULT_EDITOR_TITLE = "My Puck Editor";
+
+/**
+ * Produces the per-page <head> Metadata for a route (PCC-3407). Title and
+ * description are template-allowed properties.
+ */
+export async function resolvePageMetadata({
+  pageData,
+  path,
+  searchParams,
+}: {
+  pageData: PageData;
+  path: string;
+  searchParams: Record<string, string | string[] | undefined>;
+}): Promise<Metadata> {
+  const rootProps: Record<string, unknown> | undefined = pageData?.root.props;
+  const seo: Partial<SeoMetadata> | undefined = rootProps?._seo;
+  const rootTitle = rootProps?.title as string | undefined;
+  const rawTitle = rootTitle === DEFAULT_EDITOR_TITLE ? undefined : rootTitle;
+  const rawDescription = rootProps?.description as string | undefined;
+
+  const needsTemplates =
+    (typeof rawTitle === "string" && rawTitle.includes("{{")) ||
+    (typeof rawDescription === "string" && rawDescription.includes("{{"));
+
+  let title = rawTitle;
+  let description = rawDescription;
+  if (needsTemplates && pageData) {
+    const routeTemplateKeys = await listRouteTemplateKeysFromDatabase();
+    const referencedDatasourceIds = extractReferencedDatasourceIds(pageData);
+    const context = await loadRemoteDatasourceContext({
+      searchParams,
+      fetchImpl: fetch,
+      pagePath: path,
+      routeTemplateKeys,
+      builtinFetchers: REMOTE_DATASOURCE_FETCHERS,
+      referencedDatasourceIds,
+    });
+
+    const [resolvedTitle, resolvedDescription] = await Promise.all([
+      typeof rawTitle === "string"
+        ? resolveStringTemplates(rawTitle, context)
+        : rawTitle,
+      typeof rawDescription === "string"
+        ? resolveStringTemplates(rawDescription, context)
+        : rawDescription,
+    ]);
+
+    title = resolvedTitle;
+    description = resolvedDescription;
+  }
+
+  return buildPageMetadata({
+    seo: {
+      title,
+      description,
+      siteName: seo?.siteName,
+    },
+    path,
+  });
+}

package/template/lib/seo-metadata.ts

@@ -0,0 +1,48 @@
+import type { Metadata } from "next";
+
+/**
+ * Head-side metadata inputs. Title, description, and canonical are derived
+ * client-side (root props, request path); only siteName arrives from the
+ * backend's SeoMetadata payload.
+ */
+export interface PageHeadMetadata {
+  title?: string;
+  description?: string;
+  canonicalUrl?: string;
+  siteName?: string;
+}
+
+/**
+ * Maps head metadata to the page's <head> Metadata. Next replaces (not
+ * deep-merges) a page's openGraph over the layout's, so og:type and the env
+ * og:site_name fallback must be declared here. A relative canonical is emitted
+ * only when NEXT_PUBLIC_SITE_URL is configured to resolve it — otherwise Next
+ * would resolve it against a localhost default, and a wrong canonical is worse
+ * than none. An empty title is treated as absent.
+ */
+export function buildPageMetadata({
+  seo,
+  path,
+}: {
+  seo?: PageHeadMetadata;
+  path: string;
+}): Metadata {
+  const { description, canonicalUrl } = seo ?? {};
+  const title = seo?.title || undefined;
+  const siteName = seo?.siteName ?? process.env.NEXT_PUBLIC_SITE_NAME;
+  const canonical =
+    canonicalUrl ?? (process.env.NEXT_PUBLIC_SITE_URL ? path : undefined);
+
+  return {
+    title,
+    description,
+    ...(canonical ? { alternates: { canonical } } : {}),
+    openGraph: {
+      type: "website",
+      title,
+      description,
+      ...(canonical ? { url: canonical } : {}),
+      ...(siteName ? { siteName } : {}),
+    },
+  };
+}

package/template/package.json

@@ -7,17 +7,22 @@
     "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-ai-chat": "^0.1.0",
-    "@pantheon-systems/p1-next-sdk": "^0.6.0",
-    "@pantheon-systems/pds-toolkit-react": "2.0.0-alpha.12",
-    "@pantheon-systems/puck-css": "^0.6.0",
+    "@pantheon-systems/css-client": "^0.8.0",
+    "@pantheon-systems/p1-ai-chat": "^0.1.2",
+    "@pantheon-systems/p1-media": "^0.4.2",
+    "@pantheon-systems/p1-next-sdk": "^0.8.0",
+    "@pantheon-systems/pds-toolkit-react": "2.0.0-alpha.51",
+    "@pantheon-systems/puck-css": "^0.8.0",
     "@puckeditor/core": "^0.21.1",
     "@tailwindcss/postcss": "^4.2.2",
+    "@tailwindcss/typography": "^0.5.16",
     "classnames": "^2.5.1",
+    "isomorphic-dompurify": "^3.18.0",
     "launchdarkly-react-client-sdk": "^3.9.2",
     "next": "^16.2.6",
     "postcss": "^8.5.12",
@@ -30,7 +35,9 @@
     "@types/node": "^20.19.30",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^4.7.0",
     "eslint": "^9.27.0",
+    "tsx": "^4.23.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.5",
     "@eslint/js": "^9.27.0",

package/template/pnpm-workspace.yaml

@@ -0,0 +1,3 @@
+allowBuilds:
+  esbuild: true
+  sharp: true

package/template/public/images/p1_logo.svg

@@ -1,5 +1,12 @@
-<svg width="32" height="32" viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg">
-<path d="M0 3C0 1.34315 1.34315 0 3 0H29C30.6569 0 32 1.34315 32 3V29C32 30.6569 30.6569 32 29 32H3C1.34315 32 0 30.6569 0 29V3Z" fill="#171717"/>
-<path d="M6 7H16.9111V8.82232H18.7335V17.9112H16.9111V19.7335H9.64464V25.189H6.01139V7H6ZM15.0888 10.6333H9.63325V16.0888H15.0888V10.6333Z" fill="#FFDC28"/>
-<path d="M20.5449 7H26.0005V25.1777H22.3672V10.6333H20.5449V7Z" fill="#FFDC28"/>
+<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/puck.config.tsx

@@ -6,6 +6,7 @@ import { headingBlock } from "./components/puck/heading-block";
 import { imageBlock } from "./components/puck/image-block";
 import { gridBlock } from "./components/puck/grid-block";
 import { listBlock } from "./components/puck/list-block";
+import { mediaFigureBlock } from "./components/puck/media-figure-block";
 import { paragraphBlock } from "./components/puck/paragraph-block";
 import { quoteBlock } from "./components/puck/quote-block";
 import { puckRoot } from "./components/puck/root";
@@ -20,7 +21,7 @@ export const config = {
     },
     media: {
       title: "Media",
-      components: ["ImageBlock"],
+      components: ["ImageBlock", "MediaFigureBlock"],
     },
     data: {
       title: "Data",
@@ -44,6 +45,7 @@ export const config = {
     HeadingBlock: headingBlock,
     ParagraphBlock: paragraphBlock,
     ImageBlock: imageBlock,
+    MediaFigureBlock: mediaFigureBlock,
     GridBlock: gridBlock,
     QuoteBlock: quoteBlock,
     ListBlock: listBlock,

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

@@ -0,0 +1,177 @@
+import { describe, expect, it, vi } from "vitest";
+import { extractDescriptors } from "@pantheon-systems/puck-css/registry-sync";
+import { resolve, load, ASSET_STUB_MARKER } from "../asset-stub-hooks.mjs";
+import { filterAssetStubbedDescriptors } from "../sync-puck-registry.js";
+
+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 a branded stub 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.format).toBe("module");
+    expect(result.shortCircuit).toBe(true);
+    expect(result.source).toContain("__p1AssetStub");
+    expect(nextLoad).not.toHaveBeenCalled();
+  });
+
+  describe("branded sentinel", () => {
+    // The stub must be *recognizable* after import, so the CI sync can detect
+    // descriptors built from stubbed assets and skip them instead of writing
+    // content it cannot faithfully compute. A bare {} erases that provenance.
+
+    async function importStub(): Promise<Record<string, unknown>> {
+      const { source } = await load("asset-stub:.%2Flogo.png", {}, vi.fn());
+      const mod = (await import(
+        /* @vite-ignore */ `data:text/javascript,${encodeURIComponent(source as string)}`
+      )) as { default: Record<string, unknown> };
+      return mod.default;
+    }
+
+    it("brands the default export with __p1AssetStub", async () => {
+      const stub = await importStub();
+      expect(stub.__p1AssetStub).toBe(true);
+    });
+
+    it("returns the marker string for arbitrary property reads (placeholder.src pattern)", async () => {
+      const stub = await importStub();
+      expect(stub.src).toBe(ASSET_STUB_MARKER);
+      expect((stub as { anythingAtAll?: unknown }).anythingAtAll).toBe(ASSET_STUB_MARKER);
+    });
+
+    it("stringifies to the marker so template-literal usage stays detectable", async () => {
+      const stub = await importStub();
+      expect(String(stub)).toContain(ASSET_STUB_MARKER);
+    });
+  });
+
+  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");
+  });
+});
+
+describe("integration: stubbed asset imports hash differently than bundler-resolved values", () => {
+  // The same puck.config.tsx yields different descriptor hashes depending on
+  // who loaded it — this loader stubs asset imports while the browser bundler
+  // resolves them to real values — so the CI sync and the editor perpetually
+  // disagree about whether an asset-bearing component "changed", and the
+  // CI-written descriptor content is missing the real default values entirely.
+
+  // Evaluate the module source load() actually emits — not a hand-written {} —
+  // so these tests track the real artifact if the stub's shape ever changes.
+  async function importStubbedAsset(): Promise<Record<string, unknown>> {
+    const { source } = await load("asset-stub:.%2Frandom-image.png", {}, vi.fn());
+    const mod = (await import(
+      /* @vite-ignore */ `data:text/javascript,${encodeURIComponent(source as string)}`
+    )) as { default: Record<string, unknown> };
+    return mod.default;
+  }
+
+  function configWithImageDefault(src: unknown) {
+    return {
+      components: {
+        imageBlock: {
+          label: "Image",
+          fields: { src: { type: "text", label: "Image URL" } },
+          defaultProps: { src },
+        },
+      },
+    };
+  }
+
+  it("`placeholder.src` (stub-derived under the loader) hashes differently than the browser's URL string", async () => {
+    const stub = await importStubbedAsset();
+
+    const [ciDescriptor] = extractDescriptors(configWithImageDefault(stub.src));
+    const [browserDescriptor] = extractDescriptors(
+      configWithImageDefault("/_next/static/media/random-image.abc123.png"),
+    );
+
+    expect(ciDescriptor.name).toBe(browserDescriptor.name);
+    expect(ciDescriptor.descriptorHash).not.toBe(browserDescriptor.descriptorHash);
+  });
+
+  it("a whole stubbed import ({} under the stub) hashes differently than the browser's StaticImageData", async () => {
+    const stub = await importStubbedAsset();
+
+    const [ciDescriptor] = extractDescriptors(configWithImageDefault(stub));
+    const [browserDescriptor] = extractDescriptors(
+      configWithImageDefault({
+        src: "/_next/static/media/random-image.abc123.png",
+        width: 800,
+        height: 600,
+      }),
+    );
+
+    expect(ciDescriptor.descriptorHash).not.toBe(browserDescriptor.descriptorHash);
+  });
+
+  it("control: a plain string default hashes identically no matter who loaded the config", async () => {
+    // Same shapes as above but with a value the stub loader never touches —
+    // proves the divergence is caused by asset stubbing, not by hashing noise.
+    const [first] = extractDescriptors(configWithImageDefault("/images/static-path.png"));
+    const [second] = extractDescriptors(configWithImageDefault("/images/static-path.png"));
+
+    expect(first.descriptorHash).toBe(second.descriptorHash);
+  });
+
+  it("end to end: descriptors built from stubbed assets are detected and skipped, clean ones kept", async () => {
+    const stub = await importStubbedAsset();
+
+    const [viaPropertyRead] = extractDescriptors(configWithImageDefault(stub.src));
+    const [viaWholeImport] = extractDescriptors(configWithImageDefault(stub));
+    const [clean] = extractDescriptors(configWithImageDefault("/images/static-path.png"));
+
+    const { writable, skipped } = filterAssetStubbedDescriptors([viaPropertyRead, viaWholeImport, clean]);
+
+    expect(skipped).toHaveLength(2);
+    expect(writable).toEqual([clean]);
+  });
+});