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

package/template/components/puck/root.tsx

@@ -1,12 +1,193 @@
 import type { ReactNode } from "react";
+import { OG_TYPES, TWITTER_CARDS } from "../../lib/seo-metadata.consts";
+
+/**
+ * Fixed-vocabulary fields are dropdowns built from the lists buildPageMetadata
+ * validates against, so an option cannot drift from what reaches the tag.
+ *
+ * The default option's value is empty rather than the default itself. Storing it
+ * would freeze a value into every page, and a page carrying an explicit `website`
+ * can never pick up a template default later — so the label states the outcome
+ * while the data stays uncommitted.
+ */
+const OG_TYPE_LABELS: Record<(typeof OG_TYPES)[number], string> = {
+  website: "Website",
+  article: "Article",
+  book: "Book",
+  profile: "Profile",
+};
+
+const TWITTER_CARD_LABELS: Record<(typeof TWITTER_CARDS)[number], string> = {
+  summary: "Summary",
+  summary_large_image: "Summary with large image",
+  player: "Player",
+  app: "App",
+};
+
+const optionsWithDefault = <T extends string>(
+  values: readonly T[],
+  labels: Record<T, string>,
+  defaultLabel: string,
+) => [
+  { label: `${defaultLabel} (default)`, value: "" },
+  ...values.map((value) => ({ label: labels[value], value: value as string })),
+];
+
+// buildPageMetadata picks the large card when there is an image, so the default
+// option names whichever one an empty field will actually get.
+const twitterCardOptions = (defaultLabel: string) =>
+  optionsWithDefault(TWITTER_CARDS, TWITTER_CARD_LABELS, defaultLabel);
+
+/**
+ * Page metadata values are stored at `root.props._meta`, so they are
+ * branch-scoped and versioned like any other authored content. A page created
+ * from a template starts with that template's `_meta` copied in, the same way
+ * its content is; anything still empty after that inherits at render time.
+ *
+ * Labels are the tag names themselves, not friendly rewrites. Someone editing
+ * these is working from an SEO or social checklist that names the tags, and a
+ * label like "Social title" makes them guess which tag it writes.
+ */
+const metadataFields = {
+  ogTitle: {
+    type: "text" as const,
+    label: "og:title",
+    metadata: {
+      help: "The headline shown when this page is shared.",
+      helpWhenEmpty: "Inherited from title. Edit to override.",
+    },
+  },
+  ogDescription: {
+    type: "textarea" as const,
+    label: "og:description",
+    metadata: {
+      help: "The summary shown beneath the headline when this page is shared.",
+      helpWhenEmpty: "Inherited from description. Edit to override.",
+    },
+  },
+  ogType: {
+    type: "select" as const,
+    label: "og:type",
+    options: optionsWithDefault(OG_TYPES, OG_TYPE_LABELS, "Website"),
+    metadata: { help: "How this page is described when shared. Most pages are a website." },
+  },
+  ogImage: {
+    type: "text" as const,
+    label: "og:image",
+    metadata: {
+      help: "Full URL to the preview image. A relative path resolves against the site URL.",
+    },
+  },
+  ogLocale: {
+    type: "text" as const,
+    label: "og:locale",
+    metadata: { help: "Language and region of this page, such as en_US." },
+  },
+  // Without twitter:card, X renders no card at all and the two fields below are inert.
+  twitterCard: {
+    type: "select" as const,
+    label: "twitter:card",
+    options: twitterCardOptions("Summary"),
+    metadata: {
+      help: "How the card is laid out on X. Player and app cards need tags this site does not render.",
+    },
+  },
+  twitterTitle: {
+    type: "text" as const,
+    label: "twitter:title",
+    metadata: {
+      help: "The headline shown on X.",
+      helpWhenEmpty: "Inherited from og:title, then title. Edit to override.",
+    },
+  },
+  twitterImage: {
+    type: "text" as const,
+    label: "twitter:image",
+    metadata: {
+      help: "Full URL to the image shown on X.",
+      helpWhenEmpty: "Inherited from og:image. Edit to override.",
+    },
+  },
+};
+
+// Boilerplate from defaultProps: never offered as an inherited value, matching
+// the head tags, which refuse to ship it.
+const DEFAULT_EDITOR_TITLE = "My Puck Editor";
+
+const inheritedFrom = (value: unknown): string | undefined => {
+  const text = typeof value === "string" ? value.trim() : "";
+  return text && text !== DEFAULT_EDITOR_TITLE ? text : undefined;
+};
+
+const withPlaceholder = <T extends object>(field: T, placeholder?: string): T =>
+  placeholder ? { ...field, placeholder } : field;
+
+interface InheritedValues {
+  ogTitle?: string;
+  ogDescription?: string;
+  twitterTitle?: string;
+  twitterImage?: string;
+  twitterCardDefault?: string;
+}
+
+const buildFields = (inherited: InheritedValues = {}) => ({
+  title: { type: "text" as const },
+  description: { type: "textarea" as const },
+  _meta: {
+    type: "object" as const,
+    label: "Social & sharing",
+    metadata: { collapsible: true, defaultCollapsed: true },
+    objectFields: {
+      ...metadataFields,
+      ogTitle: withPlaceholder(metadataFields.ogTitle, inherited.ogTitle),
+      ogDescription: withPlaceholder(metadataFields.ogDescription, inherited.ogDescription),
+      twitterTitle: withPlaceholder(metadataFields.twitterTitle, inherited.twitterTitle),
+      twitterImage: withPlaceholder(metadataFields.twitterImage, inherited.twitterImage),
+      twitterCard: inherited.twitterCardDefault
+        ? {
+            ...metadataFields.twitterCard,
+            options: twitterCardOptions(inherited.twitterCardDefault),
+          }
+        : metadataFields.twitterCard,
+    },
+  },
+});
 
 export const puckRoot = {
-  fields: {
-    title: { type: "text" as const },
-    description: { type: "textarea" as const },
+  fields: buildFields(),
+  /**
+   * Shows what an empty field will inherit, as a placeholder. It has to be a
+   * placeholder and not a value: autosave persists the whole snapshot, so a
+   * derived value written into the field would be saved and the field would stop
+   * inheriting for good.
+   *
+   * Reading the source from root props is what makes this track edits — the
+   * fields slice subscribes to the root node, so changing the title re-resolves.
+   * The same is not true of Puck's `metadata`, which is why the site and
+   * template default tiers cannot be shown this way.
+   *
+   * The chains mirror buildPageMetadata in lib/seo-metadata.ts. A placeholder
+   * that disagreed with what the head actually emits would be worse than none.
+   */
+  resolveFields: (data: { props?: Record<string, unknown> }) => {
+    const props = data.props ?? {};
+    const meta = (props._meta ?? {}) as Record<string, unknown>;
+    const title = inheritedFrom(props.title);
+    const ogTitle = inheritedFrom(meta.ogTitle) ?? title;
+    const image = inheritedFrom(meta.twitterImage) ?? inheritedFrom(meta.ogImage);
+
+    return buildFields({
+      ogTitle: title,
+      ogDescription: inheritedFrom(props.description),
+      twitterTitle: ogTitle,
+      twitterImage: inheritedFrom(meta.ogImage),
+      twitterCardDefault: image
+        ? TWITTER_CARD_LABELS.summary_large_image
+        : TWITTER_CARD_LABELS.summary,
+    });
   },
   defaultProps: {
-    title: "My Puck Editor",
+    title: DEFAULT_EDITOR_TITLE,
   },
   render: (props: { children?: ReactNode; title?: string }) => {
     const { children } = props;

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/constants/assets.ts

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

package/template/eslint.config.js

@@ -81,7 +81,11 @@ export default tseslint.config(
       '@typescript-eslint/no-shadow': 'warn',
       '@typescript-eslint/no-require-imports': 'warn',
       'no-async-promise-executor': 'warn',
-      '@typescript-eslint/consistent-type-definitions': 'warn',
+      // Off deliberately. The rule's `interface` default is unsafe: interfaces have
+      // no implicit index signature, so autofixing `type X = {...}` to an interface
+      // silently breaks assignability to Record<string, unknown>. Both spellings are
+      // fine; this is not worth a footgun.
+      '@typescript-eslint/consistent-type-definitions': 'off',
       'no-useless-escape': 'warn',
       'no-useless-catch': 'warn',
       '@typescript-eslint/no-inferrable-types': 'warn',
@@ -90,7 +94,10 @@ export default tseslint.config(
       '@typescript-eslint/ban-ts-comment': 'warn',
       '@typescript-eslint/no-unused-expressions': 'warn',
       '@typescript-eslint/no-non-null-asserted-optional-chain': 'warn',
-      '@typescript-eslint/no-empty-function': 'warn',
+      // A no-op default for an optional callback is idiomatic here
+      // (`onLogout ?? (() => {})`), and the rule cannot tell it from an
+      // accidentally empty body. Still catches empty function declarations.
+      '@typescript-eslint/no-empty-function': ['warn', { allow: ['arrowFunctions', 'methods'] }],
       '@typescript-eslint/no-empty-object-type': 'warn',
       '@typescript-eslint/no-wrapper-object-types': 'warn',
       'no-constant-binary-expression': 'warn',
@@ -99,14 +106,20 @@ export default tseslint.config(
       '@typescript-eslint/no-redeclare': 'warn',
       'no-case-declarations': 'warn',
       'no-empty': 'warn',
-      '@typescript-eslint/no-dynamic-delete': 'warn',
+      // Off: `delete record[computedKey]` is the normal way to drop a cache
+      // entry or a patch path segment. The rule's alternative is switching the
+      // structure to a Map, which is a design change, not a lint fix.
+      '@typescript-eslint/no-dynamic-delete': 'off',
       'no-constant-condition': 'warn',
       'no-empty-pattern': 'warn',
       'no-var': 'warn',
       '@typescript-eslint/no-namespace': 'warn',
       '@typescript-eslint/no-extraneous-class': 'warn',
       '@typescript-eslint/unified-signatures': 'warn',
-      '@typescript-eslint/no-invalid-void-type': 'warn',
+      // Off: `request<void>(...)` for an endpoint that returns no body is the
+      // normal spelling in css-client, and that is a generic type argument —
+      // which the rule's own message calls valid.
+      '@typescript-eslint/no-invalid-void-type': 'off',
       '@typescript-eslint/no-this-alias': 'warn',
     },
   },
@@ -127,6 +140,9 @@ export default tseslint.config(
       'coverage/**',
       '**/*.d.ts',
       '**/generated/**',
+      // Vendored snapshots and test data. Linting these rewrites them, which
+      // silently breaks any test asserting byte-identical output against them.
+      '**/fixtures/**',
       '**/.puppeteerrc.cjs',
     ],
   },

package/template/lib/chatbot-flag/ai-generate.ts

@@ -0,0 +1,23 @@
+import type { DraftRequestChannel } from "@pantheon-systems/p1-ai-chat";
+
+/**
+ * Build the Create Page modal's "Generate with AI" handler, or `undefined` when the
+ * chatbot is disabled (which leaves the modal tile a placeholder).
+ *
+ * The page does not exist yet: the chat proposes the page template it should start from and
+ * creates it once the user agrees, because a document's template can only be set as it is
+ * created (PCC-3555). Until then the request carries the title and path the dialog collected.
+ */
+export function createGenerateWithAIHandler(
+  draftRequests: DraftRequestChannel,
+  enabled: boolean,
+): ((brief: string, page: { path: string; title?: string }) => void) | undefined {
+  if (!enabled) return undefined;
+  return (brief, page) => {
+    draftRequests.publish({
+      kind: "create-page",
+      brief: brief.trim(),
+      page: { path: page.path, title: page.title?.trim() ?? "" },
+    });
+  };
+}

package/template/lib/chatbot-flag/draft-request-channel.ts

@@ -0,0 +1,12 @@
+import { createDraftRequestChannel, type DraftRequestChannel } from "@pantheon-systems/p1-ai-chat";
+
+let channel: DraftRequestChannel | null = null;
+
+/**
+ * Module-level singleton, not component state: the publish and the consume happen either
+ * side of a navigation that remounts the editor tree, so a per-mount ref would drop it.
+ */
+export function getDraftRequestChannel(): DraftRequestChannel {
+  if (!channel) channel = createDraftRequestChannel();
+  return channel;
+}

package/template/lib/monsters-api.ts

@@ -35,6 +35,8 @@ function resolveMonsterIndex(params: RemoteDatasourceFetcherParams): string | un
   );
 }
 
+type MonsterItem = { index: string; name: string; url: string } & Record<string, unknown>;
+
 async function fetchMonster(
   index: string | undefined,
   fetchImpl: typeof fetch,
@@ -50,9 +52,10 @@ async function fetchMonster(
     key
     num
     species
-    types
-    abilities { first second hidden special }
-    hp attack defense spAtk spDef speed sprite
+    sprite
+    types { name }
+    abilities { first { name } second { name } hidden { name } }
+    baseStats { hp attack defense specialattack specialdefense speed }
   }
 }`,
         variables: { pokemon: index },
@@ -74,9 +77,7 @@ async function fetchMonster(
   }
 }
 
-async function fetchMonsterList(
-  fetchImpl: typeof fetch,
-): Promise<Array<{ index: string; name: string; url?: string }>> {
+async function fetchMonsterList(fetchImpl: typeof fetch): Promise<MonsterItem[]> {
   try {
     const res = await fetchImpl(GRAPHQL_POKEMON_ENDPOINT, {
       method: "POST",
@@ -85,7 +86,12 @@ async function fetchMonsterList(
         query: `query GetAllPokemon($take: Int!, $offset: Int!) {
   getAllPokemon(take: $take, offset: $offset) {
     key
+    num
     species
+    sprite
+    types { name }
+    abilities { first { name } second { name } hidden { name } }
+    baseStats { hp attack defense specialattack specialdefense speed }
   }
 }`,
         variables: { take: 200, offset: 89 },
@@ -98,14 +104,14 @@ async function fetchMonsterList(
     if (!data || typeof data !== "object" || Array.isArray(data)) return [];
     const results = (data as { getAllPokemon?: unknown }).getAllPokemon;
     if (!Array.isArray(results)) return [];
-    const out: Array<{ index: string; name: string; url?: string }> = [];
+    const out: MonsterItem[] = [];
     for (const row of results) {
       if (!row || typeof row !== "object" || Array.isArray(row)) continue;
       const r = row as Record<string, unknown>;
       const index = typeof r.key === "string" ? r.key : "";
       const name = typeof r.species === "string" ? r.species : "";
       const url = index ? `/pokemon/${index}` : undefined;
-      if (index && name) out.push({ index, name, url });
+      if (index && name && url) out.push({ ...r, index, name, url });
     }
     return out;
   } catch {

package/template/lib/page-seo.ts

@@ -0,0 +1,112 @@
+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";
+import type { PageMetaFields } 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";
+
+/**
+ * Metadata fields that accept `{{ }}`. ogType and twitterCard are absent by
+ * design: their values are checked against a union, so a template could only
+ * ever resolve to something the renderer rejects.
+ */
+const TEMPLATED_META_FIELDS = [
+  "ogTitle",
+  "ogDescription",
+  "ogImage",
+  "ogLocale",
+  "twitterTitle",
+  "twitterImage",
+] as const satisfies readonly (keyof PageMetaFields)[];
+
+const carriesTemplate = (value: unknown): value is string =>
+  typeof value === "string" && value.includes("{{");
+
+/**
+ * Produces the per-page <head> Metadata for a route (PCC-3407). Title,
+ * description and the free-text metadata fields are template-allowed.
+ */
+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 authoredMeta = rootProps?._meta as PageMetaFields | undefined;
+  const rootTitle = rootProps?.title as string | undefined;
+  const rawTitle = rootTitle === DEFAULT_EDITOR_TITLE ? undefined : rootTitle;
+  const rawDescription = rootProps?.description as string | undefined;
+
+  const templatedMeta = TEMPLATED_META_FIELDS.filter((field) =>
+    carriesTemplate(authoredMeta?.[field]),
+  );
+  const needsTemplates =
+    carriesTemplate(rawTitle) || carriesTemplate(rawDescription) || templatedMeta.length > 0;
+
+  let title = rawTitle;
+  let description = rawDescription;
+  let meta = authoredMeta;
+
+  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,
+    });
+
+    // One context load, then every templated value resolved against it. Only
+    // the fields that carry a template are resolved, so an ordinary page with a
+    // templated title does not pay for eight passes.
+    const resolveField = async (value: string) => resolveStringTemplates(value, context);
+
+    const [resolvedTitle, resolvedDescription, ...resolvedMeta] = await Promise.all([
+      carriesTemplate(rawTitle) ? resolveField(rawTitle) : rawTitle,
+      carriesTemplate(rawDescription) ? resolveField(rawDescription) : rawDescription,
+      ...templatedMeta.map((field) => resolveField(authoredMeta?.[field] as string)),
+    ]);
+
+    title = resolvedTitle;
+    description = resolvedDescription;
+    meta = {
+      ...authoredMeta,
+      ...Object.fromEntries(
+        templatedMeta.map((field, index) => [field, resolvedMeta[index]]),
+      ),
+    };
+  }
+
+  return buildPageMetadata({
+    seo: {
+      title,
+      description,
+      siteName: seo?.siteName,
+      siteDefaults: { ogImage: seo?.ogImage, ogLocale: seo?.ogLocale },
+      meta,
+    },
+    path,
+  });
+}

package/template/lib/remote-datasources.ts

@@ -3,7 +3,7 @@ import type { RemoteDatasourceDefinition } from "@pantheon-systems/puck-css/serv
 export const REMOTE_DATASOURCE_REGISTRY: RemoteDatasourceDefinition[] = [
   {
     id: "swapi",
-    label: "Star Wars API (person)",
+    label: "Star Wars character detail",
     description:
       "Person record from SWAPI. Used when editing pages that resolve a numeric person id (see resolution).",
     resolution:
@@ -29,7 +29,7 @@ export const REMOTE_DATASOURCE_REGISTRY: RemoteDatasourceDefinition[] = [
   },
   {
     id: "monster",
-    label: "Pokemon GraphQL (pokemon)",
+    label: "Pokemon detail",
     description: "Single pokemon record from GraphQL Pokemon (`getPokemon`).",
     resolution:
       "Resolved from query params (`?monster=...`, `?monsterIndex=...`, `?index=...`, then `?id=...`), preview params, or route params (`:monster`, `:monsterIndex`, `:index`, `:id`).",
@@ -61,7 +61,7 @@ export const REMOTE_DATASOURCE_REGISTRY: RemoteDatasourceDefinition[] = [
   },
   {
     id: "swapi_list",
-    label: "Star Wars API (people index)",
+    label: "Star Wars characters list",
     description:
       "First page of SWAPI `/people/` (loaded every request). Use with a List block and `markdownLinks` token.",
     resolution:
@@ -70,23 +70,28 @@ export const REMOTE_DATASOURCE_REGISTRY: RemoteDatasourceDefinition[] = [
       {
         path: "items",
         description:
-          "Array of `{ id, name }` rows from SWAPI `/people/`. In an Array field, set value to `{{ swapi_list.items }}` to hydrate cards/rows.",
-      },
-      {
-        path: "items.0.url",
-        description:
-          "Canonical SWAPI URL for each item (available as `item.url` in per-card templates).",
+          "Array of `{ id, name, url }` rows from SWAPI `/people/`. In an Array field, set value to `{{ swapi_list.items }}` to hydrate cards/rows.",
       },
       {
         path: "markdownLinks",
         description:
           'In a List block\'s items field: `{{ swapi_list.markdownLinks "/jedi/{id}" }}` (or bare `{{ swapi_list.markdownLinks }}`) -- expands to one `[name](/jedi/n)` line per person.',
       },
+      { path: "items[].id", description: "Person ID (extracted from URL)" },
+      { path: "items[].name", description: "Character name" },
+      { path: "items[].height", description: "Height" },
+      { path: "items[].mass", description: "Mass" },
+      { path: "items[].hair_color", description: "Hair color" },
+      { path: "items[].skin_color", description: "Skin color" },
+      { path: "items[].eye_color", description: "Eye color" },
+      { path: "items[].birth_year", description: "Birth year" },
+      { path: "items[].gender", description: "Gender" },
+      { path: "items[].url", description: "Canonical person URL" },
     ],
   },
   {
     id: "monster_list",
-    label: "Pokemon GraphQL (pokemon index)",
+    label: "Pokemon list",
     description:
       "Pokemon list from GraphQL Pokemon `getAllPokemon` (loaded every request).",
     resolution:
@@ -97,23 +102,16 @@ export const REMOTE_DATASOURCE_REGISTRY: RemoteDatasourceDefinition[] = [
         description:
           "Array of `{ index, name, url }` rows from `getAllPokemon` (mapped from `key` + `species`). In an Array field, set `{{ monster_list.items }}` to hydrate cards/rows.",
       },
-      {
-        path: "items.0.index",
-        description: "Pokemon slug/index (for example `bulbasaur`).",
-      },
-      {
-        path: "items.0.name",
-        description: "Display name (for example `Bulbasaur`).",
-      },
-      {
-        path: "items.0.url",
-        description: "Synthetic URL path for per-item links.",
-      },
+      { path: "items[].index", description: "Pokemon slug (from key)" },
+      { path: "items[].name", description: "Pokemon name (from species)" },
+      { path: "items[].num", description: "Pokedex number" },
+      { path: "items[].sprite", description: "Sprite URL" },
+      { path: "items[].url", description: "URL path for this pokemon" },
     ],
   },
   {
     id: "article",
-    label: "Content Publisher (article)",
+    label: "Article detail",
     description:
       "Single Content Publisher article resolved from query/preview/route params.",
     resolution:
@@ -131,7 +129,7 @@ export const REMOTE_DATASOURCE_REGISTRY: RemoteDatasourceDefinition[] = [
   },
   {
     id: "article_list",
-    label: "Content Publisher (articles index)",
+    label: "Articles list",
     description:
       "Article list from Content Publisher, loaded every request for list rendering.",
     resolution:
@@ -142,13 +140,10 @@ export const REMOTE_DATASOURCE_REGISTRY: RemoteDatasourceDefinition[] = [
         description:
           "Array of normalized `{ id, title, slug?, url? }` rows. Use `{{ article_list.items }}` to hydrate array/list blocks.",
       },
-      { path: "items.0.id", description: "Article identifier." },
-      { path: "items.0.title", description: "Article title." },
-      {
-        path: "items.0.slug",
-        description: "Article slug/path alias if present.",
-      },
-      { path: "items.0.url", description: "Canonical URL if present." },
+      { path: "items[].id", description: "Article identifier" },
+      { path: "items[].title", description: "Article title" },
+      { path: "items[].slug", description: "Slug/path alias" },
+      { path: "items[].url", description: "Canonical article URL" },
     ],
   },
 ];

package/template/lib/seo-metadata.consts.ts

@@ -0,0 +1,21 @@
+/**
+ * The fixed vocabularies shared by the renderer and the editor.
+ *
+ * Next types `og:type` and `twitter:card` as unions rather than strings, so
+ * buildPageMetadata validates against these lists and falls back rather than
+ * letting an unrecognised value reach the tag. The Puck root config builds its
+ * dropdown options from the same lists, so an option cannot offer a value the
+ * renderer will reject.
+ */
+
+export const OG_TYPES = ["website", "article", "book", "profile"] as const;
+
+export const TWITTER_CARDS = [
+  "summary",
+  "summary_large_image",
+  "player",
+  "app",
+] as const;
+
+export type OgType = (typeof OG_TYPES)[number];
+export type TwitterCard = (typeof TWITTER_CARDS)[number];