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

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

@@ -12,10 +12,15 @@
 #   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
+# 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:
@@ -49,3 +54,4 @@ jobs:
           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

@@ -12,14 +12,17 @@
   },
   "dependencies": {
     "@pantheon-systems/cpub-react-sdk": "^5.2.1",
-    "@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",
+    "@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",
@@ -32,6 +35,7 @@
     "@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",

package/template/pnpm-workspace.yaml

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

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

@@ -1,5 +1,7 @@
 import { describe, expect, it, vi } from "vitest";
-import { resolve, load } from "../asset-stub-hooks.mjs";
+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 () => {
@@ -43,13 +45,45 @@ describe("resolve", () => {
 });
 
 describe("load", () => {
-  it("returns an empty default export for asset-stub URLs without calling nextLoad", async () => {
+  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).toEqual({ format: "module", source: "export default {};", shortCircuit: true });
+    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);
@@ -62,3 +96,82 @@ describe("load", () => {
     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]);
+  });
+});

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

@@ -1,5 +1,12 @@
 import { describe, expect, it } from "vitest";
-import { validateEnv, resolveConfigModule, resolveBranchId, NoBranchMatchError } from "../sync-puck-registry.js";
+import {
+  validateEnv,
+  resolveConfigModule,
+  resolveBranchId,
+  filterAssetStubbedDescriptors,
+  NoBranchMatchError,
+} from "../sync-puck-registry.js";
+import { ASSET_STUB_MARKER } from "../asset-stub-hooks.mjs";
 
 function baseEnv(overrides: Record<string, string | undefined> = {}): Record<string, string | undefined> {
   return {
@@ -43,6 +50,19 @@ describe("validateEnv", () => {
     expect(result.branchOverride).toBe("explicit");
   });
 
+  it("reads CSS_DEFAULT_BRANCH into defaultBranchName, overriding the default", () => {
+    const result = validateEnv(baseEnv({ CSS_DEFAULT_BRANCH: "master" }));
+    expect(result.defaultBranchName).toBe("master");
+  });
+
+  it("defaults defaultBranchName to 'main' when CSS_DEFAULT_BRANCH is not set", () => {
+    // Safe because the CSS main content branch is always literally named
+    // "main": a push override of "main" resolves to the same branch either
+    // by name match or by isMain, so the default only adds semantics.
+    const result = validateEnv(baseEnv());
+    expect(result.defaultBranchName).toBe("main");
+  });
+
   it("defaults PUCK_CONFIG_PATH to puck.config.tsx", () => {
     const result = validateEnv(baseEnv());
     expect(result.puckConfigPath).toBe("puck.config.tsx");
@@ -122,3 +142,89 @@ describe("resolveBranchId", () => {
     expect(() => resolveBranchId(branches as never, "site-123", "nonexistent")).toThrow(NoBranchMatchError);
   });
 });
+
+describe("resolveBranchId default-branch semantics", () => {
+  // In CI the override is always the pushed git ref's name, so a repo whose
+  // default branch is not literally named "main" would never match the CSS
+  // main branch (whose name is always "main") — the sync silently skips on
+  // every default-branch push. When the caller also supplies the repo's
+  // default branch name, an override equal to it must resolve via isMain.
+  const branches = [
+    { id: "b-1", siteId: "site-123", name: "main", isMain: true },
+    { id: "b-2", siteId: "site-123", name: "staging", isMain: false },
+  ];
+
+  it("resolves the isMain branch when the override is the repo's default branch name", () => {
+    expect(resolveBranchId(branches as never, "site-123", "master", "master")).toBe("b-1");
+  });
+
+  it("prefers isMain over a coincidental name match for the default branch", () => {
+    const withDecoy = [...branches, { id: "b-3", siteId: "site-123", name: "master", isMain: false }];
+    expect(resolveBranchId(withDecoy as never, "site-123", "master", "master")).toBe("b-1");
+  });
+
+  it("throws NoBranchMatchError for a default-branch override when no isMain branch exists", () => {
+    const noMain = [{ id: "b-2", siteId: "site-123", name: "staging", isMain: false }];
+    expect(() => resolveBranchId(noMain as never, "site-123", "master", "master")).toThrow(NoBranchMatchError);
+  });
+
+  it("keeps plain name matching for overrides that are not the default branch", () => {
+    expect(resolveBranchId(branches as never, "site-123", "staging", "master")).toBe("b-2");
+  });
+
+  it("keeps the silent-skip path for non-default refs that match nothing", () => {
+    expect(() => resolveBranchId(branches as never, "site-123", "feature-x", "master")).toThrow(NoBranchMatchError);
+  });
+});
+
+describe("filterAssetStubbedDescriptors", () => {
+  // CI loads puck.config.tsx under the asset-stub loader, so any defaultProps
+  // value derived from an asset import is a branded sentinel, not the real
+  // bundler-resolved value. CI cannot faithfully describe those components —
+  // it skips them (loudly) and leaves them to the editor path.
+
+  const descriptor = (name: string, defaultProps: Record<string, unknown>) =>
+    ({ name, label: name, fields: [], defaultProps, descriptorHash: "h" }) as never;
+
+  it("keeps descriptors whose defaults are plain values", () => {
+    const clean = descriptor("heroBlock", { title: "Hello", count: 3, nested: { a: [1, "x"] } });
+    const { writable, skipped } = filterAssetStubbedDescriptors([clean]);
+    expect(writable).toEqual([clean]);
+    expect(skipped).toEqual([]);
+  });
+
+  it("skips a descriptor whose default carries the asset-stub marker string (placeholder.src pattern)", () => {
+    const stubbed = descriptor("imageBlock", { src: ASSET_STUB_MARKER, alt: "Mountain" });
+    const { writable, skipped } = filterAssetStubbedDescriptors([stubbed]);
+    expect(writable).toEqual([]);
+    expect(skipped.map((d: { name: string }) => d.name)).toEqual(["imageBlock"]);
+  });
+
+  it("skips a descriptor whose default is a branded stub object (whole-import pattern)", () => {
+    const stubbed = descriptor("imageBlock", { src: { __p1AssetStub: true } });
+    const { skipped } = filterAssetStubbedDescriptors([stubbed]);
+    expect(skipped).toHaveLength(1);
+  });
+
+  it("detects the marker arbitrarily deep in defaultProps", () => {
+    const stubbed = descriptor("gallery", { items: [{ media: { src: `prefix ${ASSET_STUB_MARKER}` } }] });
+    const { skipped } = filterAssetStubbedDescriptors([stubbed]);
+    expect(skipped).toHaveLength(1);
+  });
+
+  it("partitions a mixed list preserving order of writable descriptors", () => {
+    const a = descriptor("a", { t: "1" });
+    const b = descriptor("b", { src: ASSET_STUB_MARKER });
+    const c = descriptor("c", { t: "2" });
+    const { writable, skipped } = filterAssetStubbedDescriptors([a, b, c]);
+    expect(writable.map((d: { name: string }) => d.name)).toEqual(["a", "c"]);
+    expect(skipped.map((d: { name: string }) => d.name)).toEqual(["b"]);
+  });
+
+  it("does not hang on circular defaultProps", () => {
+    const circular: Record<string, unknown> = { title: "ok" };
+    circular.self = circular;
+    const { skipped } = filterAssetStubbedDescriptors([descriptor("looper", circular)]);
+    expect(skipped).toEqual([]);
+  });
+});