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

package/template/__tests__/paragraph-editor-text.test.ts

@@ -0,0 +1,79 @@
+import { readFileSync, existsSync } from "fs";
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+import { describe, expect, it } from "vitest";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const appDir = resolve(__dirname, "..");
+const componentPath = resolve(
+  appDir,
+  "components/puck/paragraph-editor-text.tsx",
+);
+const paragraphPath = resolve(appDir, "components/puck/paragraph-block.tsx");
+
+describe("ParagraphEditorText component", () => {
+  it("exists as a separate file", () => {
+    expect(existsSync(componentPath)).toBe(true);
+  });
+
+  it("is a client component", () => {
+    const content = readFileSync(componentPath, "utf-8");
+    expect(content).toMatch(/^["']use client["']/);
+  });
+
+  it("imports useResolvedPreviewState from puck-css", () => {
+    const content = readFileSync(componentPath, "utf-8");
+    expect(content).toContain("useResolvedPreviewState");
+  });
+
+  it("imports getBlockPropsById from puck-css", () => {
+    const content = readFileSync(componentPath, "utf-8");
+    expect(content).toContain("getBlockPropsById");
+  });
+
+  it("extracts raw text from element props to detect template tokens", () => {
+    const content = readFileSync(componentPath, "utf-8");
+    expect(content).toContain("extractRawText");
+    expect(content).toMatch(/\{\{/);
+  });
+
+  it("tracks focus state via onFocus, onBlur, and a mousedown document listener for click-outside", () => {
+    const content = readFileSync(componentPath, "utf-8");
+    expect(content).toContain("onFocus");
+    expect(content).toContain("onBlur");
+    expect(content).toContain('addEventListener("mousedown"');
+  });
+
+  it("uses transparent text and pointer-events overlay instead of hiding the InlineTextField", () => {
+    const content = readFileSync(componentPath, "utf-8");
+    expect(content).toContain("color: \"transparent\"");
+    expect(content).toContain("pointerEvents: \"none\"");
+  });
+
+  it("renders resolved text as sanitized HTML, not Markdown", () => {
+    const content = readFileSync(componentPath, "utf-8");
+    expect(content).toContain("sanitizeRichtextHtml");
+    expect(content).toContain("dangerouslySetInnerHTML");
+    expect(content).not.toContain("ReactMarkdown");
+  });
+});
+
+describe("paragraph-block uses ParagraphEditorText", () => {
+  const content = readFileSync(paragraphPath, "utf-8");
+
+  it("imports ParagraphEditorText", () => {
+    expect(content).toContain("ParagraphEditorText");
+  });
+
+  it("destructures id from render props", () => {
+    expect(content).toMatch(/\bid\b.*:/);
+  });
+
+  it("wraps isValidElement branch with ParagraphEditorText", () => {
+    const reactElementBranch = content.slice(
+      content.indexOf("isValidElement(text)"),
+      content.indexOf("isValidElement(text)") + 200,
+    );
+    expect(reactElementBranch).toContain("ParagraphEditorText");
+  });
+});

package/template/__tests__/puck-root-guidance.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from "vitest";
+import { puckRoot } from "../components/puck/root";
+
+/**
+ * Guidance on the page-metadata fields: help text under every field, and a
+ * placeholder showing what an empty field will inherit.
+ *
+ * The placeholder comes from `resolveFields` reading the live root props — the
+ * only tiers that exist today are the page's own title and description. It is a
+ * placeholder rather than a value on purpose: autosave persists the whole
+ * snapshot, so a derived value written into the field would be saved and the
+ * field would stop inheriting for good.
+ */
+
+type Field = {
+  type: string;
+  label?: string;
+  placeholder?: string;
+  metadata?: { help?: string; helpWhenEmpty?: string };
+};
+type ObjectField = { type: string; objectFields: Record<string, Field> };
+
+const staticMeta = (puckRoot.fields as Record<string, unknown>)._meta as ObjectField;
+
+const resolve = (props: Record<string, unknown>) => {
+  const resolveFields = puckRoot.resolveFields as (
+    data: { props: Record<string, unknown> },
+  ) => Record<string, unknown>;
+  const fields = resolveFields({ props });
+  return (fields._meta as ObjectField).objectFields;
+};
+
+const INHERITS_FROM: Record<string, string> = {
+  ogTitle: "title",
+  ogDescription: "description",
+  twitterTitle: "title",
+};
+
+describe("page-metadata field guidance", () => {
+  it("gives every metadata field help text", () => {
+    for (const [name, field] of Object.entries(staticMeta.objectFields)) {
+      expect(
+        field.metadata?.help ?? field.metadata?.helpWhenEmpty,
+        `${name} has no help text`,
+      ).toBeTruthy();
+    }
+  });
+
+  it("tells an empty inheriting field where its value comes from", () => {
+    for (const name of Object.keys(INHERITS_FROM)) {
+      expect(staticMeta.objectFields[name]?.metadata?.helpWhenEmpty).toMatch(/inherit/i);
+    }
+  });
+});
+
+describe("puckRoot.resolveFields", () => {
+  it("shows the inherited value as the placeholder", () => {
+    const fields = resolve({ title: "Q3 Launch Recap", description: "How it went" });
+
+    expect(fields.ogTitle?.placeholder).toBe("Q3 Launch Recap");
+    expect(fields.twitterTitle?.placeholder).toBe("Q3 Launch Recap");
+    expect(fields.ogDescription?.placeholder).toBe("How it went");
+  });
+
+  it("follows the same fallback chains the head tags use", () => {
+    // buildPageMetadata resolves twitter:title from ogTitle before title, and
+    // twitter:image from ogImage. A placeholder that disagreed would mislead.
+    const fields = resolve({
+      title: "Q3 Launch Recap",
+      _meta: { ogTitle: "Read the Q3 recap", ogImage: "https://cdn.example/card.png" },
+    });
+
+    expect(fields.twitterTitle?.placeholder).toBe("Read the Q3 recap");
+    expect(fields.twitterImage?.placeholder).toBe("https://cdn.example/card.png");
+  });
+
+  it("omits the placeholder when there is nothing to inherit", () => {
+    const fields = resolve({});
+
+    expect(fields.ogTitle?.placeholder).toBeUndefined();
+    expect(fields.ogDescription?.placeholder).toBeUndefined();
+  });
+
+  it("does not offer the editor's boilerplate title as an inherited value", () => {
+    // Matches the head-tag side, which refuses to ship defaultProps.title.
+    const fields = resolve({ title: "My Puck Editor" });
+
+    expect(fields.ogTitle?.placeholder).toBeUndefined();
+  });
+
+  it("resolves the same field set it declares statically", () => {
+    expect(Object.keys(resolve({ title: "x" })).sort()).toEqual(
+      Object.keys(staticMeta.objectFields).sort(),
+    );
+  });
+
+  it("leaves the declared fields unmutated, so a resolve cannot leak into the next", () => {
+    resolve({ title: "Q3 Launch Recap" });
+
+    expect(staticMeta.objectFields.ogTitle?.placeholder).toBeUndefined();
+  });
+
+  it("keeps the placeholder out of the document by never touching props", () => {
+    const props = { title: "Q3 Launch Recap", _meta: { ogTitle: "" } };
+    resolve(props);
+
+    expect(props._meta).toEqual({ ogTitle: "" });
+  });
+});

package/template/__tests__/puck-root-meta.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, it } from "vitest";
+import { puckRoot } from "../components/puck/root";
+
+/**
+ * The fixed page-metadata field set on the Puck root config.
+ *
+ * Values live at `root.props._meta` in the page snapshot — branch-scoped,
+ * versioned and autosaved for free. The field set itself is fixed: no
+ * admin-defined fields, no template or site tiers. `resolveFields` varies only
+ * the placeholders (see puck-root-guidance), never which fields exist.
+ *
+ * Fields are declared flat inside one `_meta` object field. Grouping them
+ * (SEO / Open Graph / Twitter) would mean nesting object fields, which deepens
+ * the prop paths the root-prop migration applier has to handle.
+ */
+
+type ObjectField = {
+  type: string;
+  label?: string;
+  objectFields: Record<string, { type: string; label?: string }>;
+};
+
+const metaField = (puckRoot.fields as Record<string, unknown>)._meta as ObjectField;
+
+// ogType and twitterCard are selects: their vocabulary is fixed by what Next
+// accepts for the tag. See puck-root-selects.
+const EXPECTED_FIELDS: Record<string, string> = {
+  ogTitle: "text",
+  ogDescription: "textarea",
+  ogType: "select",
+  ogImage: "text",
+  ogLocale: "text",
+  twitterCard: "select",
+  twitterTitle: "text",
+  twitterImage: "text",
+};
+
+describe("puckRoot._meta field set", () => {
+  it("is a single object field", () => {
+    expect(metaField).toBeDefined();
+    expect(metaField.type).toBe("object");
+  });
+
+  it("declares exactly the eight fixed fields, flat", () => {
+    expect(Object.keys(metaField.objectFields).sort()).toEqual(
+      Object.keys(EXPECTED_FIELDS).sort(),
+    );
+  });
+
+  it("gives each field the expected type", () => {
+    for (const [name, type] of Object.entries(EXPECTED_FIELDS)) {
+      expect(metaField.objectFields[name]?.type).toBe(type);
+    }
+  });
+
+  it("labels every field with the tag it writes", () => {
+    // Not friendly rewrites: someone editing these is working from a checklist
+    // that names the tags, and "Social title" makes them guess which one it is.
+    expect(
+      Object.fromEntries(
+        Object.keys(EXPECTED_FIELDS).map((name) => [
+          name,
+          metaField.objectFields[name]?.label,
+        ]),
+      ),
+    ).toEqual({
+      ogTitle: "og:title",
+      ogDescription: "og:description",
+      ogType: "og:type",
+      ogImage: "og:image",
+      ogLocale: "og:locale",
+      twitterCard: "twitter:card",
+      twitterTitle: "twitter:title",
+      twitterImage: "twitter:image",
+    });
+  });
+
+  it("names the group for what it holds, matching the prototype", () => {
+    expect((metaField as { label?: string }).label).toBe("Social & sharing");
+  });
+
+  it("omits ogUrl — the canonical URL is derived from the request", () => {
+    expect(metaField.objectFields).not.toHaveProperty("ogUrl");
+  });
+
+  it("includes twitterCard, without which twitter:title and twitter:image are inert", () => {
+    expect(metaField.objectFields.twitterCard).toBeDefined();
+  });
+
+  it("keeps the existing title and description fields", () => {
+    const fields = puckRoot.fields as Record<string, { type: string }>;
+    expect(fields.title?.type).toBe("text");
+    expect(fields.description?.type).toBe("textarea");
+  });
+
+  it("adds no _meta default, so no page is seeded with boilerplate metadata", () => {
+    // Empty-means-inherit (Q1): an unset field falls back at render time. A
+    // default here would freeze a value into every new page's snapshot, and
+    // would need adding to the DEFAULT_EDITOR_TITLE-style boilerplate filter.
+    expect(puckRoot.defaultProps).not.toHaveProperty("_meta");
+  });
+});

package/template/__tests__/puck-root-selects.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from "vitest";
+import { puckRoot } from "../components/puck/root";
+import { OG_TYPES, TWITTER_CARDS } from "../lib/seo-metadata.consts";
+
+/**
+ * The two metadata fields with a fixed vocabulary are dropdowns.
+ *
+ * Their options come from the same lists `buildPageMetadata` validates against,
+ * so an option cannot drift from what actually reaches the tag.
+ *
+ * The default option's value is empty rather than the default itself. Storing
+ * `website` on every page would freeze it there, and a page holding an explicit
+ * value can never pick up a template default later — so the label states the
+ * outcome while the data stays uncommitted.
+ */
+
+type Field = {
+  type: string;
+  options?: { label: string; value: string }[];
+};
+type ObjectField = { type: string; objectFields: Record<string, Field> };
+
+const staticMeta = (puckRoot.fields as Record<string, unknown>)._meta as ObjectField;
+
+const resolve = (props: Record<string, unknown>) => {
+  const resolveFields = puckRoot.resolveFields as (
+    data: { props: Record<string, unknown> },
+  ) => Record<string, unknown>;
+  return (resolveFields({ props })._meta as ObjectField).objectFields;
+};
+
+const values = (field?: Field) => field?.options?.map((option) => option.value) ?? [];
+
+describe("fixed-vocabulary metadata fields", () => {
+  it("renders as selects rather than free text", () => {
+    expect(staticMeta.objectFields.ogType?.type).toBe("select");
+    expect(staticMeta.objectFields.twitterCard?.type).toBe("select");
+  });
+
+  it("offers exactly the values the head tags accept", () => {
+    expect(values(staticMeta.objectFields.ogType).filter(Boolean)).toEqual([...OG_TYPES]);
+    expect(values(staticMeta.objectFields.twitterCard).filter(Boolean)).toEqual([
+      ...TWITTER_CARDS,
+    ]);
+  });
+
+  it("keeps an empty first option, so a page stays uncommitted", () => {
+    for (const name of ["ogType", "twitterCard"]) {
+      expect(values(staticMeta.objectFields[name])[0]).toBe("");
+    }
+  });
+
+  it("labels every option, since the tag values are not user-facing", () => {
+    for (const name of ["ogType", "twitterCard"]) {
+      const options = staticMeta.objectFields[name]?.options ?? [];
+      expect(options.length).toBeGreaterThan(1);
+      for (const option of options) {
+        expect(option.label).toBeTruthy();
+      }
+    }
+  });
+
+  it("names the og:type default, which is always website", () => {
+    expect(staticMeta.objectFields.ogType?.options?.[0]?.label).toMatch(/website/i);
+  });
+
+  it("names the default card style, which depends on whether there is an image", () => {
+    // buildPageMetadata picks summary_large_image when an image is present and
+    // summary when it is not, so the label has to follow the image field.
+    const withImage = resolve({ _meta: { ogImage: "https://cdn.example/card.png" } });
+    const without = resolve({});
+
+    expect(withImage.twitterCard?.options?.[0]?.label).toMatch(/large image/i);
+    expect(without.twitterCard?.options?.[0]?.label).toMatch(/summary/i);
+    expect(without.twitterCard?.options?.[0]?.label).not.toMatch(/large image/i);
+  });
+
+  it("varies only the default label, never the option values", () => {
+    const resolved = resolve({ _meta: { ogImage: "https://cdn.example/card.png" } });
+
+    expect(values(resolved.ogType)).toEqual(values(staticMeta.objectFields.ogType));
+    expect(values(resolved.twitterCard)).toEqual(
+      values(staticMeta.objectFields.twitterCard),
+    );
+  });
+});

package/template/__tests__/remote-datasource-fetchers.test.ts

@@ -13,8 +13,8 @@ vi.mock("@pantheon-systems/puck-css/server", async (importOriginal) => {
   return actual;
 });
 
-import { REMOTE_DATASOURCE_FETCHERS } from "../lib/remote-datasource-fetchers";
 import type { RemoteDatasourceFetcherParams } from "@pantheon-systems/puck-css/server";
+import { REMOTE_DATASOURCE_FETCHERS } from "../lib/remote-datasource-fetchers";
 
 const { PCCConvenienceFunctions } = await import(
   "@pantheon-systems/cpub-react-sdk/server"
@@ -177,7 +177,7 @@ describe("monster_list fetcher", () => {
     });
     const result = await fetcher.fetch(makeFetcherParams({ fetchImpl }));
     expect(result).toEqual({
-      items: [{ index: "bulbasaur", name: "Bulbasaur", url: "/pokemon/bulbasaur" }],
+      items: [{ key: "bulbasaur", species: "Bulbasaur", index: "bulbasaur", name: "Bulbasaur", url: "/pokemon/bulbasaur" }],
     });
   });
 });

package/template/__tests__/seo-metadata-meta.test.ts

@@ -0,0 +1,180 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { buildPageMetadata } from "../lib/seo-metadata";
+
+/**
+ * Authored page metadata (`root.props._meta`) rendered into <head>.
+ *
+ * Resolution order is: authored value → derived from title/description → omit
+ * the tag. The template and site-default tiers are not wired up yet, so an
+ * absent value must omit rather than guess.
+ */
+
+const og = (m: ReturnType<typeof buildPageMetadata>) =>
+  (m.openGraph ?? {}) as Record<string, unknown>;
+const tw = (m: ReturnType<typeof buildPageMetadata>) =>
+  (m.twitter ?? {}) as Record<string, unknown>;
+
+describe("buildPageMetadata — Open Graph from _meta", () => {
+  afterEach(() => vi.unstubAllEnvs());
+
+  it("prefers the authored og values over the page title and description", () => {
+    const meta = buildPageMetadata({
+      seo: {
+        title: "Q3 Launch Recap",
+        description: "How the launch went.",
+        meta: { ogTitle: "The launch, in numbers", ogDescription: "Charts inside." },
+      },
+      path: "/q3",
+    });
+
+    expect(og(meta).title).toBe("The launch, in numbers");
+    expect(og(meta).description).toBe("Charts inside.");
+    // The page's own <title> is unaffected by the social override.
+    expect(meta.title).toBe("Q3 Launch Recap");
+  });
+
+  it("falls back to title and description when the og fields are empty", () => {
+    const meta = buildPageMetadata({
+      seo: {
+        title: "Q3 Launch Recap",
+        description: "How the launch went.",
+        meta: { ogTitle: "", ogDescription: "" },
+      },
+      path: "/q3",
+    });
+
+    expect(og(meta).title).toBe("Q3 Launch Recap");
+    expect(og(meta).description).toBe("How the launch went.");
+  });
+
+  it("emits og:image and og:locale when authored", () => {
+    const meta = buildPageMetadata({
+      seo: {
+        title: "Q3",
+        meta: { ogImage: "https://cdn.example/hero.jpg", ogLocale: "en_US" },
+      },
+      path: "/q3",
+    });
+
+    expect(og(meta).images).toBe("https://cdn.example/hero.jpg");
+    expect(og(meta).locale).toBe("en_US");
+  });
+
+  it("omits og:image and og:locale entirely when not authored", () => {
+    const meta = buildPageMetadata({ seo: { title: "Q3" }, path: "/q3" });
+
+    expect(og(meta)).not.toHaveProperty("images");
+    expect(og(meta)).not.toHaveProperty("locale");
+  });
+
+  it("uses the authored og:type and keeps website as the default", () => {
+    expect(og(buildPageMetadata({ seo: { title: "Q3", meta: { ogType: "article" } }, path: "/q3" })).type).toBe("article");
+    expect(og(buildPageMetadata({ seo: { title: "Q3" }, path: "/q3" })).type).toBe("website");
+  });
+});
+
+describe("buildPageMetadata — Twitter card", () => {
+  it("defaults to summary_large_image when an image is available", () => {
+    const meta = buildPageMetadata({
+      seo: { title: "Q3", meta: { ogImage: "https://cdn.example/hero.jpg" } },
+      path: "/q3",
+    });
+
+    expect(tw(meta).card).toBe("summary_large_image");
+  });
+
+  it("defaults to summary when no image is available", () => {
+    const meta = buildPageMetadata({ seo: { title: "Q3" }, path: "/q3" });
+
+    expect(tw(meta).card).toBe("summary");
+  });
+
+  it("respects an authored card style", () => {
+    const meta = buildPageMetadata({
+      seo: { title: "Q3", meta: { twitterCard: "summary", ogImage: "https://cdn.example/a.jpg" } },
+      path: "/q3",
+    });
+
+    expect(tw(meta).card).toBe("summary");
+  });
+
+  it("ignores an unrecognised card style rather than emitting it", () => {
+    // The field is free text, so a typo must not produce an invalid tag.
+    const meta = buildPageMetadata({
+      seo: { title: "Q3", meta: { twitterCard: "summary_large" } },
+      path: "/q3",
+    });
+
+    expect(tw(meta).card).toBe("summary");
+  });
+
+  it("falls back through twitter → og → page for title and image", () => {
+    const meta = buildPageMetadata({
+      seo: {
+        title: "Q3 Launch Recap",
+        meta: { ogTitle: "The launch", ogImage: "https://cdn.example/og.jpg" },
+      },
+      path: "/q3",
+    });
+
+    expect(tw(meta).title).toBe("The launch");
+    expect(tw(meta).images).toBe("https://cdn.example/og.jpg");
+  });
+
+  it("prefers authored twitter values over the og ones", () => {
+    const meta = buildPageMetadata({
+      seo: {
+        title: "Q3 Launch Recap",
+        meta: {
+          ogTitle: "The launch",
+          ogImage: "https://cdn.example/og.jpg",
+          twitterTitle: "Launch, for X",
+          twitterImage: "https://cdn.example/x.jpg",
+        },
+      },
+      path: "/q3",
+    });
+
+    expect(tw(meta).title).toBe("Launch, for X");
+    expect(tw(meta).images).toBe("https://cdn.example/x.jpg");
+  });
+
+  it("omits the twitter block entirely when there is nothing to say", () => {
+    const meta = buildPageMetadata({ seo: {}, path: "/untitled" });
+
+    expect(meta.twitter).toBeUndefined();
+  });
+});
+
+describe("buildPageMetadata — unchanged behaviour", () => {
+  it("still emits title, description and siteName with no _meta present", () => {
+    const meta = buildPageMetadata({
+      seo: { title: "About", description: "Us", siteName: "Acme" },
+      path: "/about",
+    });
+
+    expect(meta.title).toBe("About");
+    expect(meta.description).toBe("Us");
+    expect(og(meta).siteName).toBe("Acme");
+  });
+});
+
+describe("buildPageMetadata — free-text fields are validated", () => {
+  it("falls back to website for an unrecognised og:type", () => {
+    // Next types og:type as a union, so an arbitrary string is both a type error
+    // and an invalid tag, and the editor field is free text.
+    const meta = buildPageMetadata({
+      seo: { title: "Q3", meta: { ogType: "artical" } },
+      path: "/q3",
+    });
+
+    expect(og(meta).type).toBe("website");
+  });
+
+  it("keeps the recognised og:type values", () => {
+    for (const type of ["website", "article", "book", "profile"]) {
+      const meta = buildPageMetadata({ seo: { title: "Q3", meta: { ogType: type } }, path: "/q3" });
+      expect(og(meta).type).toBe(type);
+    }
+  });
+});

package/template/__tests__/seo-metadata-site-defaults.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+import { buildPageMetadata } from "../lib/seo-metadata";
+
+/**
+ * Site-level social defaults, delivered on the content payload alongside
+ * og:site_name. They sit below the page's own values: a page that authors
+ * og:image wins, a page that leaves it empty inherits the site's.
+ */
+
+const og = (m: ReturnType<typeof buildPageMetadata>) =>
+  (m.openGraph ?? {}) as Record<string, unknown>;
+const tw = (m: ReturnType<typeof buildPageMetadata>) =>
+  (m.twitter ?? {}) as Record<string, unknown>;
+
+describe("buildPageMetadata — site-level defaults", () => {
+  it("uses the site og:image when the page leaves it empty", () => {
+    const meta = buildPageMetadata({
+      seo: {
+        title: "Q3 Launch Recap",
+        siteDefaults: { ogImage: "https://cdn.example/site-social.png" },
+        meta: { ogImage: "" },
+      },
+      path: "/q3",
+    });
+
+    expect(og(meta).images).toBe("https://cdn.example/site-social.png");
+  });
+
+  it("prefers the page's own og:image over the site default", () => {
+    const meta = buildPageMetadata({
+      seo: {
+        title: "Q3 Launch Recap",
+        siteDefaults: { ogImage: "https://cdn.example/site-social.png" },
+        meta: { ogImage: "https://cdn.example/page-hero.png" },
+      },
+      path: "/q3",
+    });
+
+    expect(og(meta).images).toBe("https://cdn.example/page-hero.png");
+  });
+
+  it("uses the site og:locale when the page leaves it empty", () => {
+    const meta = buildPageMetadata({
+      seo: { title: "Q3", siteDefaults: { ogLocale: "en_US" }, meta: {} },
+      path: "/q3",
+    });
+
+    expect(og(meta).locale).toBe("en_US");
+  });
+
+  it("prefers the page's own og:locale over the site default", () => {
+    const meta = buildPageMetadata({
+      seo: { title: "Q3", siteDefaults: { ogLocale: "en_US" }, meta: { ogLocale: "fr_FR" } },
+      path: "/q3",
+    });
+
+    expect(og(meta).locale).toBe("fr_FR");
+  });
+
+  it("lets an inherited image drive twitter:image and the card style", () => {
+    const meta = buildPageMetadata({
+      seo: {
+        title: "Q3",
+        siteDefaults: { ogImage: "https://cdn.example/site-social.png" },
+        meta: {},
+      },
+      path: "/q3",
+    });
+
+    expect(tw(meta).images).toBe("https://cdn.example/site-social.png");
+    expect(tw(meta).card).toBe("summary_large_image");
+  });
+
+  it("omits the tags when neither tier has a value", () => {
+    const meta = buildPageMetadata({ seo: { title: "Q3", meta: {} }, path: "/q3" });
+
+    expect(og(meta).images).toBeUndefined();
+    expect(og(meta).locale).toBeUndefined();
+  });
+});