1.2.2

dist/exports/rsc.d.ts

@@ -7,3 +7,4 @@
  */
 export { RenderBlocks } from '../modules/blocks/index.js';
 export type { BlockComponentMap, BlockData, EnhanceProps, RenderBlocksProps, } from '../modules/blocks/index.js';
+export { MediaPreconnect } from '../modules/storage/MediaPreconnect.js';

dist/exports/rsc.js

@@ -5,5 +5,6 @@
  * lives here rather than in the main package entry to keep React out of the
  * server-config bundle.
  */ export { RenderBlocks } from '../modules/blocks/index.js';
+export { MediaPreconnect } from '../modules/storage/MediaPreconnect.js';
 
 //# sourceMappingURL=rsc.js.map

dist/exports/rsc.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/exports/rsc.ts"],"sourcesContent":["/**\n * Entry point: ipal-kit/rsc\n *\n * Server-component exports. RenderBlocks is a React Server Component, so it\n * lives here rather than in the main package entry to keep React out of the\n * server-config bundle.\n */\nexport { RenderBlocks } from '../modules/blocks/index.js'\nexport type {\n  BlockComponentMap,\n  BlockData,\n  EnhanceProps,\n  RenderBlocksProps,\n} from '../modules/blocks/index.js'\n"],"names":["RenderBlocks"],"mappings":"AAAA;;;;;;CAMC,GACD,SAASA,YAAY,QAAQ,6BAA4B"}
+{"version":3,"sources":["../../src/exports/rsc.ts"],"sourcesContent":["/**\n * Entry point: ipal-kit/rsc\n *\n * Server-component exports. RenderBlocks is a React Server Component, so it\n * lives here rather than in the main package entry to keep React out of the\n * server-config bundle.\n */\nexport { RenderBlocks } from '../modules/blocks/index.js'\nexport type {\n  BlockComponentMap,\n  BlockData,\n  EnhanceProps,\n  RenderBlocksProps,\n} from '../modules/blocks/index.js'\nexport { MediaPreconnect } from '../modules/storage/MediaPreconnect.js'\n"],"names":["RenderBlocks","MediaPreconnect"],"mappings":"AAAA;;;;;;CAMC,GACD,SAASA,YAAY,QAAQ,6BAA4B;AAOzD,SAASC,eAAe,QAAQ,wCAAuC"}

dist/globals/SiteSettings/fields/general.d.ts

@@ -1,6 +1,6 @@
 import type { Field } from 'payload';
 /**
  * General site identity fields.
- * Consumed by SEO/OG (siteName, defaultShareImage) and frontend (logo).
+ * Consumed by SEO/OG (siteName, defaultShareImage) and frontend (logo, favicon).
  */
 export declare const generalFields: Field[];

dist/globals/SiteSettings/fields/general.js

@@ -1,6 +1,7 @@
+import { validateFaviconField } from '../../../modules/seo/index.js';
 /**
  * General site identity fields.
- * Consumed by SEO/OG (siteName, defaultShareImage) and frontend (logo).
+ * Consumed by SEO/OG (siteName, defaultShareImage) and frontend (logo, favicon).
  */ export const generalFields = [
     {
         name: 'siteName',
@@ -63,7 +64,7 @@
         name: 'logo',
         type: 'upload',
         admin: {
-            description: 'Primary site logo.'
+            description: 'Primary site logo. Also used for Organization structured data (buildOrganizationJsonLd).'
         },
         relationTo: 'media'
     },
@@ -79,7 +80,14 @@
         name: 'favicon',
         type: 'upload',
         admin: {
-            description: 'Square source icon (PNG or SVG) for the browser tab. Rendered by the frontend.'
+            description: 'Square icon, PNG or SVG, min. 48×48px (Google requires this to show it in search). Rendered via buildIconsMetadata.'
+        },
+        hooks: {
+            // Warns the editor at save time if the favicon is too small (<48×48) or
+            // not square — Google won't display such favicons in search results.
+            beforeValidate: [
+                validateFaviconField
+            ]
         },
         relationTo: 'media'
     }

dist/globals/SiteSettings/fields/general.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../src/globals/SiteSettings/fields/general.ts"],"sourcesContent":["import type { Field } from 'payload'\n\n/**\n * General site identity fields.\n * Consumed by SEO/OG (siteName, defaultShareImage) and frontend (logo).\n */\nexport const generalFields: Field[] = [\n  {\n    name: 'siteName',\n    type: 'text',\n    admin: {\n      description: 'Used in page titles and Open Graph metadata.',\n    },\n    localized: true,\n    required: true,\n  },\n  {\n    name: 'titleOrder',\n    type: 'select',\n    admin: {\n      description: 'Which comes first in browser tabs.',\n    },\n    defaultValue: 'page-first',\n    options: [\n      { label: 'Page first  —  About Us | Acme', value: 'page-first' },\n      { label: 'Site first  —  Acme | About Us', value: 'site-first' },\n    ],\n  },\n  {\n    name: 'titleSeparator',\n    type: 'select',\n    admin: {\n      description: 'Separates the page title from the site name in browser tabs.',\n    },\n    defaultValue: '|',\n    options: [\n      { label: 'Pipe  —  Page | Site', value: '|' },\n      { label: 'Dash  —  Page – Site', value: '–' },\n      { label: 'Hyphen  —  Page - Site', value: '-' },\n      { label: 'Bullet  —  Page · Site', value: '·' },\n      { label: 'Slash  —  Page / Site', value: '/' },\n    ],\n  },\n  {\n    name: 'logo',\n    type: 'upload',\n    admin: {\n      description: 'Primary site logo.',\n    },\n    relationTo: 'media',\n  },\n  {\n    name: 'defaultShareImage',\n    type: 'upload',\n    admin: {\n      description: 'Fallback Open Graph image when a page has none.',\n    },\n    relationTo: 'media',\n  },\n  {\n    name: 'favicon',\n    type: 'upload',\n    admin: {\n      description: 'Square source icon (PNG or SVG) for the browser tab. Rendered by the frontend.',\n    },\n    relationTo: 'media',\n  },\n]\n"],"names":["generalFields","name","type","admin","description","localized","required","defaultValue","options","label","value","relationTo"],"mappings":"AAEA;;;CAGC,GACD,OAAO,MAAMA,gBAAyB;IACpC;QACEC,MAAM;QACNC,MAAM;QACNC,OAAO;YACLC,aAAa;QACf;QACAC,WAAW;QACXC,UAAU;IACZ;IACA;QACEL,MAAM;QACNC,MAAM;QACNC,OAAO;YACLC,aAAa;QACf;QACAG,cAAc;QACdC,SAAS;YACP;gBAAEC,OAAO;gBAAkCC,OAAO;YAAa;YAC/D;gBAAED,OAAO;gBAAkCC,OAAO;YAAa;SAChE;IACH;IACA;QACET,MAAM;QACNC,MAAM;QACNC,OAAO;YACLC,aAAa;QACf;QACAG,cAAc;QACdC,SAAS;YACP;gBAAEC,OAAO;gBAAwBC,OAAO;YAAI;YAC5C;gBAAED,OAAO;gBAAwBC,OAAO;YAAI;YAC5C;gBAAED,OAAO;gBAA0BC,OAAO;YAAI;YAC9C;gBAAED,OAAO;gBAA0BC,OAAO;YAAI;YAC9C;gBAAED,OAAO;gBAAyBC,OAAO;YAAI;SAC9C;IACH;IACA;QACET,MAAM;QACNC,MAAM;QACNC,OAAO;YACLC,aAAa;QACf;QACAO,YAAY;IACd;IACA;QACEV,MAAM;QACNC,MAAM;QACNC,OAAO;YACLC,aAAa;QACf;QACAO,YAAY;IACd;IACA;QACEV,MAAM;QACNC,MAAM;QACNC,OAAO;YACLC,aAAa;QACf;QACAO,YAAY;IACd;CACD,CAAA"}
+{"version":3,"sources":["../../../../src/globals/SiteSettings/fields/general.ts"],"sourcesContent":["import type { Field } from 'payload'\n\nimport { validateFaviconField } from '../../../modules/seo/index.js'\n\n/**\n * General site identity fields.\n * Consumed by SEO/OG (siteName, defaultShareImage) and frontend (logo, favicon).\n */\nexport const generalFields: Field[] = [\n  {\n    name: 'siteName',\n    type: 'text',\n    admin: {\n      description: 'Used in page titles and Open Graph metadata.',\n    },\n    localized: true,\n    required: true,\n  },\n  {\n    name: 'titleOrder',\n    type: 'select',\n    admin: {\n      description: 'Which comes first in browser tabs.',\n    },\n    defaultValue: 'page-first',\n    options: [\n      { label: 'Page first  —  About Us | Acme', value: 'page-first' },\n      { label: 'Site first  —  Acme | About Us', value: 'site-first' },\n    ],\n  },\n  {\n    name: 'titleSeparator',\n    type: 'select',\n    admin: {\n      description: 'Separates the page title from the site name in browser tabs.',\n    },\n    defaultValue: '|',\n    options: [\n      { label: 'Pipe  —  Page | Site', value: '|' },\n      { label: 'Dash  —  Page – Site', value: '–' },\n      { label: 'Hyphen  —  Page - Site', value: '-' },\n      { label: 'Bullet  —  Page · Site', value: '·' },\n      { label: 'Slash  —  Page / Site', value: '/' },\n    ],\n  },\n  {\n    name: 'logo',\n    type: 'upload',\n    admin: {\n      description:\n        'Primary site logo. Also used for Organization structured data (buildOrganizationJsonLd).',\n    },\n    relationTo: 'media',\n  },\n  {\n    name: 'defaultShareImage',\n    type: 'upload',\n    admin: {\n      description: 'Fallback Open Graph image when a page has none.',\n    },\n    relationTo: 'media',\n  },\n  {\n    name: 'favicon',\n    type: 'upload',\n    admin: {\n      description:\n        'Square icon, PNG or SVG, min. 48×48px (Google requires this to show it in search). Rendered via buildIconsMetadata.',\n    },\n    hooks: {\n      // Warns the editor at save time if the favicon is too small (<48×48) or\n      // not square — Google won't display such favicons in search results.\n      beforeValidate: [validateFaviconField],\n    },\n    relationTo: 'media',\n  },\n]\n"],"names":["validateFaviconField","generalFields","name","type","admin","description","localized","required","defaultValue","options","label","value","relationTo","hooks","beforeValidate"],"mappings":"AAEA,SAASA,oBAAoB,QAAQ,gCAA+B;AAEpE;;;CAGC,GACD,OAAO,MAAMC,gBAAyB;IACpC;QACEC,MAAM;QACNC,MAAM;QACNC,OAAO;YACLC,aAAa;QACf;QACAC,WAAW;QACXC,UAAU;IACZ;IACA;QACEL,MAAM;QACNC,MAAM;QACNC,OAAO;YACLC,aAAa;QACf;QACAG,cAAc;QACdC,SAAS;YACP;gBAAEC,OAAO;gBAAkCC,OAAO;YAAa;YAC/D;gBAAED,OAAO;gBAAkCC,OAAO;YAAa;SAChE;IACH;IACA;QACET,MAAM;QACNC,MAAM;QACNC,OAAO;YACLC,aAAa;QACf;QACAG,cAAc;QACdC,SAAS;YACP;gBAAEC,OAAO;gBAAwBC,OAAO;YAAI;YAC5C;gBAAED,OAAO;gBAAwBC,OAAO;YAAI;YAC5C;gBAAED,OAAO;gBAA0BC,OAAO;YAAI;YAC9C;gBAAED,OAAO;gBAA0BC,OAAO;YAAI;YAC9C;gBAAED,OAAO;gBAAyBC,OAAO;YAAI;SAC9C;IACH;IACA;QACET,MAAM;QACNC,MAAM;QACNC,OAAO;YACLC,aACE;QACJ;QACAO,YAAY;IACd;IACA;QACEV,MAAM;QACNC,MAAM;QACNC,OAAO;YACLC,aAAa;QACf;QACAO,YAAY;IACd;IACA;QACEV,MAAM;QACNC,MAAM;QACNC,OAAO;YACLC,aACE;QACJ;QACAQ,OAAO;YACL,wEAAwE;YACxE,qEAAqE;YACrEC,gBAAgB;gBAACd;aAAqB;QACxC;QACAY,YAAY;IACd;CACD,CAAA"}

dist/index.d.ts

@@ -29,6 +29,8 @@ export type { GlobalQueryOptions } from './modules/payload/index.js';
 export { getGlobal, getSiteIntegrations, getSiteSettings, SITE_INTEGRATIONS_SLUG, SITE_SETTINGS_SLUG, } from './modules/payload/index.js';
 export { buildSecurityHeaders } from './modules/security/index.js';
 export type { BuildSecurityHeadersArgs, SecurityHeader } from './modules/security/index.js';
+export { buildFaqJsonLd, buildIconsMetadata, buildLocalBusinessJsonLd, buildOrganizationJsonLd, buildServiceJsonLd, validateFaviconField, } from './modules/seo/index.js';
+export { buildBreadcrumbJsonLd, buildSiteNavigationJsonLd, buildWebSiteJsonLd, } from './modules/seo/index.js';
 export type { PageMetadata, SeoMeta, SeoOption } from './modules/seo/index.js';
 export { buildHreflangAlternates, buildMetadata, composeTitle } from './modules/seo/index.js';
 export type { AutoFillMapping, RobotsRules, SitemapEntry } from './modules/seo/index.js';

dist/index.js

@@ -18,6 +18,10 @@ export { getNotificationTexts, NOTIFICATION_FALLBACK, resolveFormMessage } from
 export { ALL_SYSTEM_PAGE_ROLES, getSystemPagePath } from './modules/pages/index.js';
 export { getGlobal, getSiteIntegrations, getSiteSettings, SITE_INTEGRATIONS_SLUG, SITE_SETTINGS_SLUG } from './modules/payload/index.js';
 export { buildSecurityHeaders } from './modules/security/index.js';
+export { buildFaqJsonLd, buildIconsMetadata, buildLocalBusinessJsonLd, buildOrganizationJsonLd, buildServiceJsonLd, validateFaviconField } from './modules/seo/index.js';
+// Structured data (schema.org JSON-LD) — brand/sitelink signals for Google.
+// WebSite (+ optional SearchAction), BreadcrumbList (per page), SiteNavigation.
+export { buildBreadcrumbJsonLd, buildSiteNavigationJsonLd, buildWebSiteJsonLd } from './modules/seo/index.js';
 export { buildHreflangAlternates, buildMetadata, composeTitle } from './modules/seo/index.js';
 export { buildAutoFillMetaHook, buildRobots, buildSitemapEntries, createMetadataGenerator, createPageMetadata, injectAutoFillMeta } from './modules/seo/index.js';
 export { buildSlugField, toSlug } from './modules/slug/index.js';

dist/modules/frontend/createContentHelpers.d.ts

@@ -1,14 +1,8 @@
 import type { BasePayload, SanitizedConfig } from 'payload';
-import type { ArchiveEntries, ContentOption, ResolvedRoute } from '../content/index.js';
+import type { ContentOption, ResolvedRoute, ArchiveEntries } from '../content/index.js';
 import type { I18nConfig } from '../i18n/index.js';
-import type { RobotsRules, SitemapEntry } from '../seo/index.js';
+import type { SitemapEntry, RobotsRules } from '../seo/index.js';
 type CreateContentHelpersArgs = {
-    /**
-     * Absolute site origin for sitemap/robots URLs. Falls back to
-     * NEXT_PUBLIC_SERVER_URL, then to a relative origin (which most crawlers
-     * reject, so set one in production).
-     */
-    baseUrl?: string;
     /**
      * The client's payload config promise (the default export of payload.config).
      * Passed in because the plugin never imports the client's config directly.
@@ -16,15 +10,21 @@ type CreateContentHelpersArgs = {
     config: Promise<SanitizedConfig> | SanitizedConfig;
     /** Archive-backed collections, same value as the plugin option. */
     content?: ContentOption;
+    /** SiteSettings global slug. Defaults to 'site-settings'. */
+    settingsSlug?: string;
+    /** Pages collection slug. Defaults to 'pages'. */
+    pagesSlug?: string;
     /**
      * i18n config. Required only if you want the ready-made `sitemap` / `robots`
      * handlers — they need the locale list to emit hreflang.
      */
     i18n?: I18nConfig;
-    /** Pages collection slug. Defaults to 'pages'. */
+    /**
-    pagesSlug?: string;
+     * Absolute site origin for sitemap/robots URLs. Falls back to
-    /** SiteSettings global slug. Defaults to 'site-settings'. */
+     * NEXT_PUBLIC_SERVER_URL, then to a relative origin (which most crawlers
-    settingsSlug?: string;
+     * reject, so set one in production).
+     */
+    baseUrl?: string;
 };
 /**
  * Bundles the per-request data helpers a frontend needs — the same cached
@@ -52,13 +52,13 @@ type CreateContentHelpersArgs = {
  * a URL is, fetching gets the listing. Metadata generation needs the first and
  * not the second, and a page component composes them in two obvious lines.
  */
-export declare function createContentHelpers({ baseUrl, config, content, i18n, pagesSlug, settingsSlug, }: CreateContentHelpersArgs): {
+export declare function createContentHelpers({ config, content, settingsSlug, pagesSlug, i18n, baseUrl, }: CreateContentHelpersArgs): {
     getCachedPayload: () => Promise<BasePayload>;
     getConfiguredLocales: () => Promise<string[]>;
-    getEntries: (collection: string, locale: string, page: number, perPage: number) => Promise<ArchiveEntries>;
     getSettings: (locale: string) => Promise<import("payload").JsonObject>;
-    resolveRoute: (locale: string, segments: string[] | undefined, page: number) => Promise<null | ResolvedRoute>;
+    resolveRoute: (locale: string, segments: string[] | undefined, page: number) => Promise<ResolvedRoute | null>;
-    robots: () => RobotsRules;
+    getEntries: (collection: string, locale: string, page: number, perPage: number) => Promise<ArchiveEntries>;
     sitemap: () => Promise<SitemapEntry[]>;
+    robots: () => RobotsRules;
 };
 export {};

dist/modules/frontend/createContentHelpers.js

@@ -1,7 +1,7 @@
-import { getPayload } from 'payload';
 import { cache } from 'react';
-import { getArchiveEntries, resolveRoute as resolveRouteRaw } from '../content/index.js';
+import { getPayload } from 'payload';
-import { buildRobots, buildSitemapEntries } from '../seo/index.js';
+import { resolveRoute as resolveRouteRaw, getArchiveEntries } from '../content/index.js';
+import { buildSitemapEntries, buildRobots } from '../seo/index.js';
 /**
  * Bundles the per-request data helpers a frontend needs — the same cached
  * wrappers every project was writing by hand (getPayload, settings, locale
@@ -27,7 +27,7 @@ import { buildRobots, buildSitemapEntries } from '../seo/index.js';
  * `resolveRoute` and `getEntries` are separate on purpose: routing decides what
  * a URL is, fetching gets the listing. Metadata generation needs the first and
  * not the second, and a page component composes them in two obvious lines.
- */ export function createContentHelpers({ baseUrl, config, content, i18n, pagesSlug = 'pages', settingsSlug = 'site-settings' }) {
+ */ export function createContentHelpers({ config, content, settingsSlug = 'site-settings', pagesSlug = 'pages', i18n, baseUrl }) {
     const origin = baseUrl ?? process.env.NEXT_PUBLIC_SERVER_URL ?? '';
     const getCachedPayload = cache(async ()=>getPayload({
             config: await config
@@ -40,29 +40,29 @@ import { buildRobots, buildSitemapEntries } from '../seo/index.js';
         const payload = await getCachedPayload();
         return payload.findGlobal({
             slug: settingsSlug,
-            depth: 2,
+            locale: locale,
-            locale: locale
+            depth: 2
         });
     });
     /** What does this URL point at? Routing only — no listing data. */ const resolveRoute = cache(async (locale, segments, page)=>{
         const payload = await getCachedPayload();
         return resolveRouteRaw({
-            content,
-            locale,
-            page,
-            pagesSlug,
             payload,
+            locale,
             segments,
+            page,
+            content,
+            pagesSlug,
             settingsSlug
         });
     });
     /** One page of a collection's entries, for an archive listing. */ const getEntries = cache(async (collection, locale, page, perPage)=>{
         const payload = await getCachedPayload();
         return getArchiveEntries({
+            payload,
             collection,
             locale,
             page,
-            payload,
             perPage
         });
     });
@@ -73,19 +73,39 @@ import { buildRobots, buildSitemapEntries } from '../seo/index.js';
    * ```ts
    * // app/sitemap.ts
    * export { sitemap as default } from '@/lib/content'
+   * export const dynamic = 'force-dynamic'  // generate at runtime, not build
    * ```
+   *
+   * IMPORTANT — container deploys (Coolify/Docker/Railway/CI): Next treats
+   * sitemap.ts as STATIC by default and prerenders it during `next build`, which
+   * calls into Payload → the database. The build container usually has no access
+   * to the internal Docker network, so the DB connection fails (ENOTFOUND) and
+   * the build dies. Two defenses:
+   *   1. `export const dynamic = 'force-dynamic'` in app/sitemap.ts — skips build
+   *      prerender, generates at runtime when the DB is reachable (recommended).
+   *   2. This handler also catches DB errors and returns [] so that even without
+   *      (1) the build won't crash — it just ships an empty sitemap until the
+   *      next runtime regeneration. (1) is still preferred; (2) is a safety net.
    */ const sitemap = cache(async ()=>{
         if (!i18n) {
             throw new Error('[ipal] createContentHelpers: pass `i18n` to use the sitemap handler.');
         }
-        return buildSitemapEntries({
+        try {
-            baseUrl: origin,
+            return await buildSitemapEntries({
+                payload: await getCachedPayload(),
                 config: i18n,
+                baseUrl: origin,
                 content,
                 pagesSlug,
-            payload: await getCachedPayload(),
                 settingsSlug
             });
+        } catch (error) {
+            // DB unreachable (typically a container build with no DB network) — return
+            // an empty sitemap instead of failing the build. Runtime regeneration will
+            // produce the real one once the DB is reachable. See dynamic='force-dynamic'.
+            console.warn('[ipal] sitemap: could not reach the database, returning empty entries ' + "(add `export const dynamic = 'force-dynamic'` to app/sitemap.ts to " + 'generate at runtime and avoid build-time DB access):', error);
+            return [];
+        }
     });
     /**
    * Ready-made handler for Next's `app/robots.ts`. Re-export directly:
@@ -100,11 +120,11 @@ import { buildRobots, buildSitemapEntries } from '../seo/index.js';
     return {
         getCachedPayload,
         getConfiguredLocales,
-        getEntries,
         getSettings,
         resolveRoute,
-        robots,
+        getEntries,
-        sitemap
+        sitemap,
+        robots
     };
 }
 

dist/modules/seo/buildBreadcrumbJsonLd.d.ts

@@ -0,0 +1,40 @@
+type Crumb = {
+    /** Visible name of the breadcrumb (e.g. 'Usługi'). */
+    name: string;
+    /** Absolute URL of this crumb (e.g. 'https://example.com/pl/uslugi'). */
+    url: string;
+};
+/**
+ * Builds BreadcrumbList JSON-LD (schema.org) for a page's position in the site
+ * hierarchy. Google can show breadcrumbs in the result (Dom › Usługi › Detailing)
+ * and uses them to understand structure — a signal that helps navigational
+ * results and sitelinks.
+ *
+ * Unlike Organization/WebSite (site-wide, root layout), breadcrumbs are
+ * PER-PAGE — build them from the page's ancestry and emit on that page:
+ *
+ *   import { buildBreadcrumbJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildBreadcrumbJsonLd([
+ *     { name: 'Strona główna', url: `${base}/pl` },
+ *     { name: 'Usługi', url: `${base}/pl/uslugi` },
+ *     { name: 'Detailing', url: `${base}/pl/uslugi/detailing` },
+ *   ])
+ *   <script type="application/ld+json" ... />
+ *
+ * The crumb data comes from the page's real position (parent pages / URL path),
+ * NOT hardcoded. Derive it from the resolved route, not a static list.
+ *
+ * Returns null for an empty/single crumb list — a one-item breadcrumb isn't
+ * meaningful and shouldn't be emitted.
+ */
+export declare function buildBreadcrumbJsonLd(crumbs: Crumb[]): {
+    '@context': string;
+    '@type': string;
+    itemListElement: {
+        name: string;
+        '@type': string;
+        item: string;
+        position: number;
+    }[];
+} | null;
+export {};

dist/modules/seo/buildBreadcrumbJsonLd.js

@@ -0,0 +1,39 @@
+/**
+ * Builds BreadcrumbList JSON-LD (schema.org) for a page's position in the site
+ * hierarchy. Google can show breadcrumbs in the result (Dom › Usługi › Detailing)
+ * and uses them to understand structure — a signal that helps navigational
+ * results and sitelinks.
+ *
+ * Unlike Organization/WebSite (site-wide, root layout), breadcrumbs are
+ * PER-PAGE — build them from the page's ancestry and emit on that page:
+ *
+ *   import { buildBreadcrumbJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildBreadcrumbJsonLd([
+ *     { name: 'Strona główna', url: `${base}/pl` },
+ *     { name: 'Usługi', url: `${base}/pl/uslugi` },
+ *     { name: 'Detailing', url: `${base}/pl/uslugi/detailing` },
+ *   ])
+ *   <script type="application/ld+json" ... />
+ *
+ * The crumb data comes from the page's real position (parent pages / URL path),
+ * NOT hardcoded. Derive it from the resolved route, not a static list.
+ *
+ * Returns null for an empty/single crumb list — a one-item breadcrumb isn't
+ * meaningful and shouldn't be emitted.
+ */ export function buildBreadcrumbJsonLd(crumbs) {
+    if (!crumbs || crumbs.length < 2) {
+        return null;
+    }
+    return {
+        '@context': 'https://schema.org',
+        '@type': 'BreadcrumbList',
+        itemListElement: crumbs.map((crumb, index)=>({
+                name: crumb.name,
+                '@type': 'ListItem',
+                item: crumb.url,
+                position: index + 1
+            }))
+    };
+}
+
+//# sourceMappingURL=buildBreadcrumbJsonLd.js.map

dist/modules/seo/buildBreadcrumbJsonLd.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/modules/seo/buildBreadcrumbJsonLd.ts"],"sourcesContent":["type Crumb = {\n  /** Visible name of the breadcrumb (e.g. 'Usługi'). */\n  name: string\n  /** Absolute URL of this crumb (e.g. 'https://example.com/pl/uslugi'). */\n  url: string\n}\n\n/**\n * Builds BreadcrumbList JSON-LD (schema.org) for a page's position in the site\n * hierarchy. Google can show breadcrumbs in the result (Dom › Usługi › Detailing)\n * and uses them to understand structure — a signal that helps navigational\n * results and sitelinks.\n *\n * Unlike Organization/WebSite (site-wide, root layout), breadcrumbs are\n * PER-PAGE — build them from the page's ancestry and emit on that page:\n *\n *   import { buildBreadcrumbJsonLd } from '@intecion/ipal-kit'\n *   const jsonLd = buildBreadcrumbJsonLd([\n *     { name: 'Strona główna', url: `${base}/pl` },\n *     { name: 'Usługi', url: `${base}/pl/uslugi` },\n *     { name: 'Detailing', url: `${base}/pl/uslugi/detailing` },\n *   ])\n *   <script type=\"application/ld+json\" ... />\n *\n * The crumb data comes from the page's real position (parent pages / URL path),\n * NOT hardcoded. Derive it from the resolved route, not a static list.\n *\n * Returns null for an empty/single crumb list — a one-item breadcrumb isn't\n * meaningful and shouldn't be emitted.\n */\nexport function buildBreadcrumbJsonLd(crumbs: Crumb[]) {\n  if (!crumbs || crumbs.length < 2) {return null}\n\n  return {\n    '@context': 'https://schema.org',\n    '@type': 'BreadcrumbList',\n    itemListElement: crumbs.map((crumb, index) => ({\n      name: crumb.name,\n      '@type': 'ListItem',\n      item: crumb.url,\n      position: index + 1,\n    })),\n  }\n}\n"],"names":["buildBreadcrumbJsonLd","crumbs","length","itemListElement","map","crumb","index","name","item","url","position"],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;CAsBC,GACD,OAAO,SAASA,sBAAsBC,MAAe;IACnD,IAAI,CAACA,UAAUA,OAAOC,MAAM,GAAG,GAAG;QAAC,OAAO;IAAI;IAE9C,OAAO;QACL,YAAY;QACZ,SAAS;QACTC,iBAAiBF,OAAOG,GAAG,CAAC,CAACC,OAAOC,QAAW,CAAA;gBAC7CC,MAAMF,MAAME,IAAI;gBAChB,SAAS;gBACTC,MAAMH,MAAMI,GAAG;gBACfC,UAAUJ,QAAQ;YACpB,CAAA;IACF;AACF"}

dist/modules/seo/buildFaqJsonLd.d.ts

@@ -0,0 +1,33 @@
+type FaqItem = {
+    answer: string;
+    question: string;
+};
+/**
+ * Builds FAQPage JSON-LD (schema.org) from Q&A pairs. Google can show these as
+ * expandable FAQ rich results under the page, taking more SERP space and helping
+ * with voice/AI answers. Strong for service landing pages.
+ *
+ * Feed it the SAME questions/answers rendered on the page (from an FAQ block in
+ * the panel) — the structured data must match visible content, or Google may
+ * flag it. Never invent Q&A that isn't on the page.
+ *
+ *   import { buildFaqJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildFaqJsonLd(
+ *     faqBlock.items.map(i => ({ question: i.question, answer: i.answer }))
+ *   )
+ *
+ * Returns null for empty list.
+ */
+export declare function buildFaqJsonLd(items: FaqItem[]): {
+    '@context': string;
+    '@type': string;
+    mainEntity: {
+        name: string;
+        '@type': string;
+        acceptedAnswer: {
+            '@type': string;
+            text: string;
+        };
+    }[];
+} | null;
+export {};

dist/modules/seo/buildFaqJsonLd.js

@@ -0,0 +1,34 @@
+/**
+ * Builds FAQPage JSON-LD (schema.org) from Q&A pairs. Google can show these as
+ * expandable FAQ rich results under the page, taking more SERP space and helping
+ * with voice/AI answers. Strong for service landing pages.
+ *
+ * Feed it the SAME questions/answers rendered on the page (from an FAQ block in
+ * the panel) — the structured data must match visible content, or Google may
+ * flag it. Never invent Q&A that isn't on the page.
+ *
+ *   import { buildFaqJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildFaqJsonLd(
+ *     faqBlock.items.map(i => ({ question: i.question, answer: i.answer }))
+ *   )
+ *
+ * Returns null for empty list.
+ */ export function buildFaqJsonLd(items) {
+    if (!items || items.length === 0) {
+        return null;
+    }
+    return {
+        '@context': 'https://schema.org',
+        '@type': 'FAQPage',
+        mainEntity: items.map((item)=>({
+                name: item.question,
+                '@type': 'Question',
+                acceptedAnswer: {
+                    '@type': 'Answer',
+                    text: item.answer
+                }
+            }))
+    };
+}
+
+//# sourceMappingURL=buildFaqJsonLd.js.map

dist/modules/seo/buildFaqJsonLd.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/modules/seo/buildFaqJsonLd.ts"],"sourcesContent":["type FaqItem = {\n  answer: string\n  question: string\n}\n\n/**\n * Builds FAQPage JSON-LD (schema.org) from Q&A pairs. Google can show these as\n * expandable FAQ rich results under the page, taking more SERP space and helping\n * with voice/AI answers. Strong for service landing pages.\n *\n * Feed it the SAME questions/answers rendered on the page (from an FAQ block in\n * the panel) — the structured data must match visible content, or Google may\n * flag it. Never invent Q&A that isn't on the page.\n *\n *   import { buildFaqJsonLd } from '@intecion/ipal-kit'\n *   const jsonLd = buildFaqJsonLd(\n *     faqBlock.items.map(i => ({ question: i.question, answer: i.answer }))\n *   )\n *\n * Returns null for empty list.\n */\nexport function buildFaqJsonLd(items: FaqItem[]) {\n  if (!items || items.length === 0) {return null}\n\n  return {\n    '@context': 'https://schema.org',\n    '@type': 'FAQPage',\n    mainEntity: items.map((item) => ({\n      name: item.question,\n      '@type': 'Question',\n      acceptedAnswer: {\n        '@type': 'Answer',\n        text: item.answer,\n      },\n    })),\n  }\n}\n"],"names":["buildFaqJsonLd","items","length","mainEntity","map","item","name","question","acceptedAnswer","text","answer"],"mappings":"AAKA;;;;;;;;;;;;;;;CAeC,GACD,OAAO,SAASA,eAAeC,KAAgB;IAC7C,IAAI,CAACA,SAASA,MAAMC,MAAM,KAAK,GAAG;QAAC,OAAO;IAAI;IAE9C,OAAO;QACL,YAAY;QACZ,SAAS;QACTC,YAAYF,MAAMG,GAAG,CAAC,CAACC,OAAU,CAAA;gBAC/BC,MAAMD,KAAKE,QAAQ;gBACnB,SAAS;gBACTC,gBAAgB;oBACd,SAAS;oBACTC,MAAMJ,KAAKK,MAAM;gBACnB;YACF,CAAA;IACF;AACF"}

dist/modules/seo/buildIconsMetadata.d.ts

@@ -0,0 +1,33 @@
+import type { Metadata } from 'next';
+type MediaLike = {
+    height?: null | number;
+    mimeType?: null | string;
+    url?: null | string;
+    width?: null | number;
+} | null | undefined;
+/**
+ * Builds Next.js `icons` metadata (favicon / apple-touch-icon) from the panel's
+ * favicon upload, so the browser tab AND Google get a proper <link rel="icon">.
+ *
+ * Why the plugin must do this (not the project): favicon-in-Google has strict
+ * rules — a real <link rel="icon"> in <head>, square, ≥48×48, at a stable URL.
+ * Leaving it to each project meant inconsistent hand-rolled tags and no favicon
+ * in search results. This generates the tags correctly, every time, from the
+ * panel field.
+ *
+ * Favicon is GLOBAL (same across pages), so call this once in the ROOT layout's
+ * generateMetadata — not per page:
+ *
+ *   import { buildIconsMetadata } from '@intecion/ipal-kit'
+ *   export async function generateMetadata(): Promise<Metadata> {
+ *     const settings = await getSettings(locale)
+ *     return buildIconsMetadata(settings.favicon)
+ *   }
+ *
+ * Google notes: it caches favicons separately and slowly (days/weeks), and only
+ * shows them for icons it deems valid. Warn on too-small icons at upload time
+ * (see the media validation hook) so editors don't ship a <48px favicon Google
+ * will reject.
+ */
+export declare function buildIconsMetadata(favicon: MediaLike): Metadata;
+export {};

dist/modules/seo/buildIconsMetadata.js

@@ -0,0 +1,54 @@
+/**
+ * Builds Next.js `icons` metadata (favicon / apple-touch-icon) from the panel's
+ * favicon upload, so the browser tab AND Google get a proper <link rel="icon">.
+ *
+ * Why the plugin must do this (not the project): favicon-in-Google has strict
+ * rules — a real <link rel="icon"> in <head>, square, ≥48×48, at a stable URL.
+ * Leaving it to each project meant inconsistent hand-rolled tags and no favicon
+ * in search results. This generates the tags correctly, every time, from the
+ * panel field.
+ *
+ * Favicon is GLOBAL (same across pages), so call this once in the ROOT layout's
+ * generateMetadata — not per page:
+ *
+ *   import { buildIconsMetadata } from '@intecion/ipal-kit'
+ *   export async function generateMetadata(): Promise<Metadata> {
+ *     const settings = await getSettings(locale)
+ *     return buildIconsMetadata(settings.favicon)
+ *   }
+ *
+ * Google notes: it caches favicons separately and slowly (days/weeks), and only
+ * shows them for icons it deems valid. Warn on too-small icons at upload time
+ * (see the media validation hook) so editors don't ship a <48px favicon Google
+ * will reject.
+ */ export function buildIconsMetadata(favicon) {
+    const url = favicon?.url;
+    if (!url) {
+        return {};
+    }
+    const isSvg = favicon?.mimeType === 'image/svg+xml' || url.endsWith('.svg');
+    return {
+        icons: {
+            // Main favicon. SVG scales; PNG should be ≥48×48 (ideally 96 or 192).
+            icon: isSvg ? [
+                {
+                    type: 'image/svg+xml',
+                    url
+                }
+            ] : [
+                {
+                    sizes: 'any',
+                    url
+                }
+            ],
+            // Apple touch icon (home-screen bookmark on iOS). Reuses the same asset.
+            apple: [
+                {
+                    url
+                }
+            ]
+        }
+    };
+}
+
+//# sourceMappingURL=buildIconsMetadata.js.map

dist/modules/seo/buildIconsMetadata.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/modules/seo/buildIconsMetadata.ts"],"sourcesContent":["import type { Metadata } from 'next'\n\ntype MediaLike =\n  | { height?: null | number; mimeType?: null | string; url?: null | string; width?: null | number }\n  | null\n  | undefined\n\n/**\n * Builds Next.js `icons` metadata (favicon / apple-touch-icon) from the panel's\n * favicon upload, so the browser tab AND Google get a proper <link rel=\"icon\">.\n *\n * Why the plugin must do this (not the project): favicon-in-Google has strict\n * rules — a real <link rel=\"icon\"> in <head>, square, ≥48×48, at a stable URL.\n * Leaving it to each project meant inconsistent hand-rolled tags and no favicon\n * in search results. This generates the tags correctly, every time, from the\n * panel field.\n *\n * Favicon is GLOBAL (same across pages), so call this once in the ROOT layout's\n * generateMetadata — not per page:\n *\n *   import { buildIconsMetadata } from '@intecion/ipal-kit'\n *   export async function generateMetadata(): Promise<Metadata> {\n *     const settings = await getSettings(locale)\n *     return buildIconsMetadata(settings.favicon)\n *   }\n *\n * Google notes: it caches favicons separately and slowly (days/weeks), and only\n * shows them for icons it deems valid. Warn on too-small icons at upload time\n * (see the media validation hook) so editors don't ship a <48px favicon Google\n * will reject.\n */\nexport function buildIconsMetadata(favicon: MediaLike): Metadata {\n  const url = favicon?.url\n  if (!url) {return {}}\n\n  const isSvg = favicon?.mimeType === 'image/svg+xml' || url.endsWith('.svg')\n\n  return {\n    icons: {\n      // Main favicon. SVG scales; PNG should be ≥48×48 (ideally 96 or 192).\n      icon: isSvg ? [{ type: 'image/svg+xml', url }] : [{ sizes: 'any', url }],\n      // Apple touch icon (home-screen bookmark on iOS). Reuses the same asset.\n      apple: [{ url }],\n    },\n  }\n}\n"],"names":["buildIconsMetadata","favicon","url","isSvg","mimeType","endsWith","icons","icon","type","sizes","apple"],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;CAuBC,GACD,OAAO,SAASA,mBAAmBC,OAAkB;IACnD,MAAMC,MAAMD,SAASC;IACrB,IAAI,CAACA,KAAK;QAAC,OAAO,CAAC;IAAC;IAEpB,MAAMC,QAAQF,SAASG,aAAa,mBAAmBF,IAAIG,QAAQ,CAAC;IAEpE,OAAO;QACLC,OAAO;YACL,sEAAsE;YACtEC,MAAMJ,QAAQ;gBAAC;oBAAEK,MAAM;oBAAiBN;gBAAI;aAAE,GAAG;gBAAC;oBAAEO,OAAO;oBAAOP;gBAAI;aAAE;YACxE,yEAAyE;YACzEQ,OAAO;gBAAC;oBAAER;gBAAI;aAAE;QAClB;IACF;AACF"}

dist/modules/seo/buildLocalBusinessJsonLd.d.ts

@@ -0,0 +1,71 @@
+type MediaLike = {
+    url?: null | string;
+} | null | undefined;
+type Address = {
+    city?: string;
+    country?: string;
+    postalCode?: string;
+    region?: string;
+    street?: string;
+};
+type LocalBusinessJsonLdArgs = {
+    address?: Address;
+    /** Geo coordinates for maps/local search. */
+    geo?: {
+        latitude: number;
+        longitude: number;
+    };
+    image?: MediaLike;
+    logo?: MediaLike;
+    name: string;
+    /** Opening hours, e.g. ['Mo-Fr 08:00-18:00', 'Sa 09:00-14:00']. */
+    openingHours?: string[];
+    priceRange?: string;
+    sameAs?: string[];
+    /** Business phone, e.g. '+48 123 456 789'. */
+    telephone?: string;
+    url: string;
+};
+/**
+ * Builds LocalBusiness JSON-LD (schema.org) — the key structured data for LOCAL
+ * SEO. Helps Google show the business in local results / map pack with address,
+ * hours, phone. Strong signal for "usługa + miasto" queries.
+ *
+ * All data from the panel (company global) — nothing hardcoded. Emit once in the
+ * root layout (business is site-wide):
+ *
+ *   import { buildLocalBusinessJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildLocalBusinessJsonLd({
+ *     name: company.name, url: baseUrl, telephone: company.phone,
+ *     address: company.address, openingHours: company.hours,
+ *   })
+ *
+ * For a more specific type (e.g. 'Dentist', 'Plumber'), override @type in the
+ * returned object — schema.org has many LocalBusiness subtypes.
+ */
+export declare function buildLocalBusinessJsonLd({ name, address, geo, image, logo, openingHours, priceRange, sameAs, telephone, url, }: LocalBusinessJsonLdArgs): {
+    sameAs?: string[] | undefined;
+    priceRange?: string | undefined;
+    openingHours?: string[] | undefined;
+    geo?: {
+        '@type': string;
+        latitude: number;
+        longitude: number;
+    } | undefined;
+    address?: {
+        addressCountry?: string | undefined;
+        addressRegion?: string | undefined;
+        postalCode?: string | undefined;
+        addressLocality?: string | undefined;
+        streetAddress?: string | undefined;
+        '@type': string;
+    } | undefined;
+    logo?: string | undefined;
+    image?: string | undefined;
+    telephone?: string | undefined;
+    name: string;
+    '@context': string;
+    '@type': string;
+    url: string;
+};
+export {};

dist/modules/seo/buildLocalBusinessJsonLd.js

@@ -0,0 +1,73 @@
+/**
+ * Builds LocalBusiness JSON-LD (schema.org) — the key structured data for LOCAL
+ * SEO. Helps Google show the business in local results / map pack with address,
+ * hours, phone. Strong signal for "usługa + miasto" queries.
+ *
+ * All data from the panel (company global) — nothing hardcoded. Emit once in the
+ * root layout (business is site-wide):
+ *
+ *   import { buildLocalBusinessJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildLocalBusinessJsonLd({
+ *     name: company.name, url: baseUrl, telephone: company.phone,
+ *     address: company.address, openingHours: company.hours,
+ *   })
+ *
+ * For a more specific type (e.g. 'Dentist', 'Plumber'), override @type in the
+ * returned object — schema.org has many LocalBusiness subtypes.
+ */ export function buildLocalBusinessJsonLd({ name, address, geo, image, logo, openingHours, priceRange, sameAs, telephone, url }) {
+    const logoUrl = logo?.url;
+    const imageUrl = image?.url ?? logoUrl;
+    return {
+        name,
+        '@context': 'https://schema.org',
+        '@type': 'LocalBusiness',
+        url,
+        ...telephone ? {
+            telephone
+        } : {},
+        ...imageUrl ? {
+            image: imageUrl.startsWith('http') ? imageUrl : `${url}${imageUrl}`
+        } : {},
+        ...logoUrl ? {
+            logo: logoUrl.startsWith('http') ? logoUrl : `${url}${logoUrl}`
+        } : {},
+        ...address ? {
+            address: {
+                '@type': 'PostalAddress',
+                ...address.street ? {
+                    streetAddress: address.street
+                } : {},
+                ...address.city ? {
+                    addressLocality: address.city
+                } : {},
+                ...address.postalCode ? {
+                    postalCode: address.postalCode
+                } : {},
+                ...address.region ? {
+                    addressRegion: address.region
+                } : {},
+                ...address.country ? {
+                    addressCountry: address.country
+                } : {}
+            }
+        } : {},
+        ...geo ? {
+            geo: {
+                '@type': 'GeoCoordinates',
+                latitude: geo.latitude,
+                longitude: geo.longitude
+            }
+        } : {},
+        ...openingHours && openingHours.length > 0 ? {
+            openingHours
+        } : {},
+        ...priceRange ? {
+            priceRange
+        } : {},
+        ...sameAs && sameAs.length > 0 ? {
+            sameAs
+        } : {}
+    };
+}
+
+//# sourceMappingURL=buildLocalBusinessJsonLd.js.map

dist/modules/seo/buildLocalBusinessJsonLd.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/modules/seo/buildLocalBusinessJsonLd.ts"],"sourcesContent":["type MediaLike = { url?: null | string } | null | undefined\n\ntype Address = {\n  city?: string\n  country?: string // ISO code, e.g. 'PL'\n  postalCode?: string\n  region?: string\n  street?: string\n}\n\ntype LocalBusinessJsonLdArgs = {\n  address?: Address\n  /** Geo coordinates for maps/local search. */\n  geo?: { latitude: number; longitude: number }\n  image?: MediaLike\n  logo?: MediaLike\n  name: string\n  /** Opening hours, e.g. ['Mo-Fr 08:00-18:00', 'Sa 09:00-14:00']. */\n  openingHours?: string[]\n  priceRange?: string // e.g. '$$'\n  sameAs?: string[]\n  /** Business phone, e.g. '+48 123 456 789'. */\n  telephone?: string\n  url: string\n}\n\n/**\n * Builds LocalBusiness JSON-LD (schema.org) — the key structured data for LOCAL\n * SEO. Helps Google show the business in local results / map pack with address,\n * hours, phone. Strong signal for \"usługa + miasto\" queries.\n *\n * All data from the panel (company global) — nothing hardcoded. Emit once in the\n * root layout (business is site-wide):\n *\n *   import { buildLocalBusinessJsonLd } from '@intecion/ipal-kit'\n *   const jsonLd = buildLocalBusinessJsonLd({\n *     name: company.name, url: baseUrl, telephone: company.phone,\n *     address: company.address, openingHours: company.hours,\n *   })\n *\n * For a more specific type (e.g. 'Dentist', 'Plumber'), override @type in the\n * returned object — schema.org has many LocalBusiness subtypes.\n */\nexport function buildLocalBusinessJsonLd({\n  name,\n  address,\n  geo,\n  image,\n  logo,\n  openingHours,\n  priceRange,\n  sameAs,\n  telephone,\n  url,\n}: LocalBusinessJsonLdArgs) {\n  const logoUrl = logo?.url\n  const imageUrl = image?.url ?? logoUrl\n\n  return {\n    name,\n    '@context': 'https://schema.org',\n    '@type': 'LocalBusiness',\n    url,\n    ...(telephone ? { telephone } : {}),\n    ...(imageUrl ? { image: imageUrl.startsWith('http') ? imageUrl : `${url}${imageUrl}` } : {}),\n    ...(logoUrl ? { logo: logoUrl.startsWith('http') ? logoUrl : `${url}${logoUrl}` } : {}),\n    ...(address\n      ? {\n          address: {\n            '@type': 'PostalAddress',\n            ...(address.street ? { streetAddress: address.street } : {}),\n            ...(address.city ? { addressLocality: address.city } : {}),\n            ...(address.postalCode ? { postalCode: address.postalCode } : {}),\n            ...(address.region ? { addressRegion: address.region } : {}),\n            ...(address.country ? { addressCountry: address.country } : {}),\n          },\n        }\n      : {}),\n    ...(geo\n      ? { geo: { '@type': 'GeoCoordinates', latitude: geo.latitude, longitude: geo.longitude } }\n      : {}),\n    ...(openingHours && openingHours.length > 0 ? { openingHours } : {}),\n    ...(priceRange ? { priceRange } : {}),\n    ...(sameAs && sameAs.length > 0 ? { sameAs } : {}),\n  }\n}\n"],"names":["buildLocalBusinessJsonLd","name","address","geo","image","logo","openingHours","priceRange","sameAs","telephone","url","logoUrl","imageUrl","startsWith","street","streetAddress","city","addressLocality","postalCode","region","addressRegion","country","addressCountry","latitude","longitude","length"],"mappings":"AA0BA;;;;;;;;;;;;;;;;CAgBC,GACD,OAAO,SAASA,yBAAyB,EACvCC,IAAI,EACJC,OAAO,EACPC,GAAG,EACHC,KAAK,EACLC,IAAI,EACJC,YAAY,EACZC,UAAU,EACVC,MAAM,EACNC,SAAS,EACTC,GAAG,EACqB;IACxB,MAAMC,UAAUN,MAAMK;IACtB,MAAME,WAAWR,OAAOM,OAAOC;IAE/B,OAAO;QACLV;QACA,YAAY;QACZ,SAAS;QACTS;QACA,GAAID,YAAY;YAAEA;QAAU,IAAI,CAAC,CAAC;QAClC,GAAIG,WAAW;YAAER,OAAOQ,SAASC,UAAU,CAAC,UAAUD,WAAW,GAAGF,MAAME,UAAU;QAAC,IAAI,CAAC,CAAC;QAC3F,GAAID,UAAU;YAAEN,MAAMM,QAAQE,UAAU,CAAC,UAAUF,UAAU,GAAGD,MAAMC,SAAS;QAAC,IAAI,CAAC,CAAC;QACtF,GAAIT,UACA;YACEA,SAAS;gBACP,SAAS;gBACT,GAAIA,QAAQY,MAAM,GAAG;oBAAEC,eAAeb,QAAQY,MAAM;gBAAC,IAAI,CAAC,CAAC;gBAC3D,GAAIZ,QAAQc,IAAI,GAAG;oBAAEC,iBAAiBf,QAAQc,IAAI;gBAAC,IAAI,CAAC,CAAC;gBACzD,GAAId,QAAQgB,UAAU,GAAG;oBAAEA,YAAYhB,QAAQgB,UAAU;gBAAC,IAAI,CAAC,CAAC;gBAChE,GAAIhB,QAAQiB,MAAM,GAAG;oBAAEC,eAAelB,QAAQiB,MAAM;gBAAC,IAAI,CAAC,CAAC;gBAC3D,GAAIjB,QAAQmB,OAAO,GAAG;oBAAEC,gBAAgBpB,QAAQmB,OAAO;gBAAC,IAAI,CAAC,CAAC;YAChE;QACF,IACA,CAAC,CAAC;QACN,GAAIlB,MACA;YAAEA,KAAK;gBAAE,SAAS;gBAAkBoB,UAAUpB,IAAIoB,QAAQ;gBAAEC,WAAWrB,IAAIqB,SAAS;YAAC;QAAE,IACvF,CAAC,CAAC;QACN,GAAIlB,gBAAgBA,aAAamB,MAAM,GAAG,IAAI;YAAEnB;QAAa,IAAI,CAAC,CAAC;QACnE,GAAIC,aAAa;YAAEA;QAAW,IAAI,CAAC,CAAC;QACpC,GAAIC,UAAUA,OAAOiB,MAAM,GAAG,IAAI;YAAEjB;QAAO,IAAI,CAAC,CAAC;IACnD;AACF"}

dist/modules/seo/buildMetadata.d.ts

@@ -19,6 +19,11 @@ export type PageMetadata = {
         locale?: string;
         title: string;
     };
+    /** robots directives — set to noindex/follow for legal/thin/search pages. */
+    robots?: {
+        follow: boolean;
+        index: boolean;
+    };
     title: string;
 };
 type BuildMetadataArgs = {
@@ -35,6 +40,13 @@ type BuildMetadataArgs = {
     meta?: null | SeoMeta;
     /** Page title or site name first. Defaults to 'page-first'. */
     order?: TitleOrder;
+    /**
+     * The document's own title (e.g. page.title = 'Sprzątanie biur'). Used as the
+     * page-title source when meta.title is empty — the browser tab and search
+     * result should show the page name, not go blank, when an editor didn't fill
+     * the SEO title. Priority: titleOverride > meta.title > pageTitle.
+     */
+    pageTitle?: null | string;
     /**
      * Localized segment the document lives under (an archive page's slugs).
      * Feeds both canonical and hreflang, so /pl/artykuly/moj-post and
@@ -65,5 +77,5 @@ type BuildMetadataArgs = {
  * pieces (meta group, site name, image URL, localized slugs) and passes them
  * in — the plugin composes, it doesn't fetch.
  */
-export declare function buildMetadata({ baseUrl, config, homeSlug, imageUrl, locale, meta, order, prefix, query, separator, siteName, slugs, }: BuildMetadataArgs): PageMetadata;
+export declare function buildMetadata({ baseUrl, config, homeSlug, imageUrl, locale, meta, order, pageTitle, prefix, query, separator, siteName, slugs, }: BuildMetadataArgs): PageMetadata;
 export {};

dist/modules/seo/buildMetadata.js

@@ -9,13 +9,16 @@ import { buildHreflangAlternates } from './hreflang.js';
  * Designed for use inside Next.js `generateMetadata`. The caller resolves the
  * pieces (meta group, site name, image URL, localized slugs) and passes them
  * in — the plugin composes, it doesn't fetch.
- */ export function buildMetadata({ baseUrl, config, homeSlug = 'home', imageUrl, locale, meta, order, prefix, query, separator, siteName, slugs }) {
+ */ export function buildMetadata({ baseUrl, config, homeSlug = 'home', imageUrl, locale, meta, order, pageTitle, prefix, query, separator, siteName, slugs }) {
-    // titleOverride wins outright: an editor who filled it in wants that exact
+    // Title source priority: titleOverride (exact, wins outright) > meta.title
-    // string in the tab, not a composition.
+    // (SEO title an editor set) > pageTitle (the document's own name). This means
+    // a page with no SEO title still shows its name (e.g. 'Sprzątanie biur')
+    // composed with the site name, instead of just the site name or a blank.
     const override = meta?.titleOverride?.trim();
+    const resolvedPageTitle = meta?.title?.trim() || pageTitle?.trim() || undefined;
     const title = override || composeTitle({
         order,
-        pageTitle: meta?.title,
+        pageTitle: resolvedPageTitle,
         separator,
         siteName
     });
@@ -69,7 +72,15 @@ import { buildHreflangAlternates } from './hreflang.js';
                 images
             },
             locale
+        },
+        // noindex → tell search engines to exclude the page but still follow links
+        // (authority flows through). For legal/thin/search-result pages.
+        ...meta?.noindex ? {
+            robots: {
+                follow: true,
+                index: false
             }
+        } : {}
     };
 }
 

dist/modules/seo/buildOrganizationJsonLd.d.ts

@@ -0,0 +1,41 @@
+type MediaLike = {
+    url?: null | string;
+} | null | undefined;
+type OrganizationJsonLdArgs = {
+    /** Logo media (from panel). Google uses this for brand knowledge panels. */
+    logo?: MediaLike;
+    /** Organization / site name. */
+    name: string;
+    /** Optional social / official profile URLs (sameAs). */
+    sameAs?: string[];
+    /** Absolute site URL (https://…). */
+    url: string;
+};
+/**
+ * Builds Organization JSON-LD (schema.org) — helps Google associate the site
+ * with a brand: name, logo, official links. Improves how the site appears in
+ * search (brand recognition, logo in knowledge panels) and is a signal used
+ * alongside favicon for identity.
+ *
+ * Returns a plain object; the project renders it as a <script type="application/
+ * ld+json"> in the root layout:
+ *
+ *   import { buildOrganizationJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildOrganizationJsonLd({
+ *     name: settings.siteName, url: baseUrl, logo: settings.logo,
+ *   })
+ *   <script type="application/ld+json"
+ *     dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }} />
+ *
+ * Data comes from the panel (siteName, logo) — nothing hardcoded. Emit once in
+ * the root layout (Organization is site-wide, not per page).
+ */
+export declare function buildOrganizationJsonLd({ name, logo, sameAs, url }: OrganizationJsonLdArgs): {
+    sameAs?: string[] | undefined;
+    logo?: string | undefined;
+    name: string;
+    '@context': string;
+    '@type': string;
+    url: string;
+};
+export {};

dist/modules/seo/buildOrganizationJsonLd.js

@@ -0,0 +1,35 @@
+/**
+ * Builds Organization JSON-LD (schema.org) — helps Google associate the site
+ * with a brand: name, logo, official links. Improves how the site appears in
+ * search (brand recognition, logo in knowledge panels) and is a signal used
+ * alongside favicon for identity.
+ *
+ * Returns a plain object; the project renders it as a <script type="application/
+ * ld+json"> in the root layout:
+ *
+ *   import { buildOrganizationJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildOrganizationJsonLd({
+ *     name: settings.siteName, url: baseUrl, logo: settings.logo,
+ *   })
+ *   <script type="application/ld+json"
+ *     dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }} />
+ *
+ * Data comes from the panel (siteName, logo) — nothing hardcoded. Emit once in
+ * the root layout (Organization is site-wide, not per page).
+ */ export function buildOrganizationJsonLd({ name, logo, sameAs, url }) {
+    const logoUrl = logo?.url;
+    return {
+        name,
+        '@context': 'https://schema.org',
+        '@type': 'Organization',
+        url,
+        ...logoUrl ? {
+            logo: logoUrl.startsWith('http') ? logoUrl : `${url}${logoUrl}`
+        } : {},
+        ...sameAs && sameAs.length > 0 ? {
+            sameAs
+        } : {}
+    };
+}
+
+//# sourceMappingURL=buildOrganizationJsonLd.js.map

dist/modules/seo/buildOrganizationJsonLd.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/modules/seo/buildOrganizationJsonLd.ts"],"sourcesContent":["type MediaLike = { url?: null | string } | null | undefined\n\ntype OrganizationJsonLdArgs = {\n  /** Logo media (from panel). Google uses this for brand knowledge panels. */\n  logo?: MediaLike\n  /** Organization / site name. */\n  name: string\n  /** Optional social / official profile URLs (sameAs). */\n  sameAs?: string[]\n  /** Absolute site URL (https://…). */\n  url: string\n}\n\n/**\n * Builds Organization JSON-LD (schema.org) — helps Google associate the site\n * with a brand: name, logo, official links. Improves how the site appears in\n * search (brand recognition, logo in knowledge panels) and is a signal used\n * alongside favicon for identity.\n *\n * Returns a plain object; the project renders it as a <script type=\"application/\n * ld+json\"> in the root layout:\n *\n *   import { buildOrganizationJsonLd } from '@intecion/ipal-kit'\n *   const jsonLd = buildOrganizationJsonLd({\n *     name: settings.siteName, url: baseUrl, logo: settings.logo,\n *   })\n *   <script type=\"application/ld+json\"\n *     dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }} />\n *\n * Data comes from the panel (siteName, logo) — nothing hardcoded. Emit once in\n * the root layout (Organization is site-wide, not per page).\n */\nexport function buildOrganizationJsonLd({ name, logo, sameAs, url }: OrganizationJsonLdArgs) {\n  const logoUrl = logo?.url\n\n  return {\n    name,\n    '@context': 'https://schema.org',\n    '@type': 'Organization',\n    url,\n    ...(logoUrl ? { logo: logoUrl.startsWith('http') ? logoUrl : `${url}${logoUrl}` } : {}),\n    ...(sameAs && sameAs.length > 0 ? { sameAs } : {}),\n  }\n}\n"],"names":["buildOrganizationJsonLd","name","logo","sameAs","url","logoUrl","startsWith","length"],"mappings":"AAaA;;;;;;;;;;;;;;;;;;CAkBC,GACD,OAAO,SAASA,wBAAwB,EAAEC,IAAI,EAAEC,IAAI,EAAEC,MAAM,EAAEC,GAAG,EAA0B;IACzF,MAAMC,UAAUH,MAAME;IAEtB,OAAO;QACLH;QACA,YAAY;QACZ,SAAS;QACTG;QACA,GAAIC,UAAU;YAAEH,MAAMG,QAAQC,UAAU,CAAC,UAAUD,UAAU,GAAGD,MAAMC,SAAS;QAAC,IAAI,CAAC,CAAC;QACtF,GAAIF,UAAUA,OAAOI,MAAM,GAAG,IAAI;YAAEJ;QAAO,IAAI,CAAC,CAAC;IACnD;AACF"}

dist/modules/seo/buildServiceJsonLd.d.ts

@@ -0,0 +1,39 @@
+type ServiceJsonLdArgs = {
+    /** Area served, e.g. 'Wrocław' or ['Wrocław', 'Oława']. */
+    areaServed?: string | string[];
+    description?: string;
+    /** Service name, e.g. 'Sprzątanie biur'. */
+    name: string;
+    /** Provider (business) name. */
+    providerName: string;
+    /** Service type / category. */
+    serviceType?: string;
+    url: string;
+};
+/**
+ * Builds Service JSON-LD (schema.org) for a service offering. Helps Google
+ * understand "what this page sells" — useful for service landing pages
+ * ("usługa + miasto"). Pairs well with LocalBusiness (the provider).
+ *
+ * Per-page (each service page emits its own), data from the panel:
+ *
+ *   import { buildServiceJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildServiceJsonLd({
+ *     name: page.serviceName, providerName: company.name,
+ *     url: pageUrl, areaServed: 'Wrocław',
+ *   })
+ */
+export declare function buildServiceJsonLd({ name, areaServed, description, providerName, serviceType, url, }: ServiceJsonLdArgs): {
+    serviceType?: string | undefined;
+    areaServed?: string | string[] | undefined;
+    description?: string | undefined;
+    name: string;
+    '@context': string;
+    '@type': string;
+    provider: {
+        name: string;
+        '@type': string;
+        url: string;
+    };
+};
+export {};

dist/modules/seo/buildServiceJsonLd.js

@@ -0,0 +1,35 @@
+/**
+ * Builds Service JSON-LD (schema.org) for a service offering. Helps Google
+ * understand "what this page sells" — useful for service landing pages
+ * ("usługa + miasto"). Pairs well with LocalBusiness (the provider).
+ *
+ * Per-page (each service page emits its own), data from the panel:
+ *
+ *   import { buildServiceJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildServiceJsonLd({
+ *     name: page.serviceName, providerName: company.name,
+ *     url: pageUrl, areaServed: 'Wrocław',
+ *   })
+ */ export function buildServiceJsonLd({ name, areaServed, description, providerName, serviceType, url }) {
+    return {
+        name,
+        '@context': 'https://schema.org',
+        '@type': 'Service',
+        provider: {
+            name: providerName,
+            '@type': 'LocalBusiness',
+            url
+        },
+        ...description ? {
+            description
+        } : {},
+        ...areaServed ? {
+            areaServed
+        } : {},
+        ...serviceType ? {
+            serviceType
+        } : {}
+    };
+}
+
+//# sourceMappingURL=buildServiceJsonLd.js.map

dist/modules/seo/buildServiceJsonLd.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/modules/seo/buildServiceJsonLd.ts"],"sourcesContent":["type ServiceJsonLdArgs = {\n  /** Area served, e.g. 'Wrocław' or ['Wrocław', 'Oława']. */\n  areaServed?: string | string[]\n  description?: string\n  /** Service name, e.g. 'Sprzątanie biur'. */\n  name: string\n  /** Provider (business) name. */\n  providerName: string\n  /** Service type / category. */\n  serviceType?: string\n  url: string\n}\n\n/**\n * Builds Service JSON-LD (schema.org) for a service offering. Helps Google\n * understand \"what this page sells\" — useful for service landing pages\n * (\"usługa + miasto\"). Pairs well with LocalBusiness (the provider).\n *\n * Per-page (each service page emits its own), data from the panel:\n *\n *   import { buildServiceJsonLd } from '@intecion/ipal-kit'\n *   const jsonLd = buildServiceJsonLd({\n *     name: page.serviceName, providerName: company.name,\n *     url: pageUrl, areaServed: 'Wrocław',\n *   })\n */\nexport function buildServiceJsonLd({\n  name,\n  areaServed,\n  description,\n  providerName,\n  serviceType,\n  url,\n}: ServiceJsonLdArgs) {\n  return {\n    name,\n    '@context': 'https://schema.org',\n    '@type': 'Service',\n    provider: {\n      name: providerName,\n      '@type': 'LocalBusiness',\n      url,\n    },\n    ...(description ? { description } : {}),\n    ...(areaServed ? { areaServed } : {}),\n    ...(serviceType ? { serviceType } : {}),\n  }\n}\n"],"names":["buildServiceJsonLd","name","areaServed","description","providerName","serviceType","url","provider"],"mappings":"AAaA;;;;;;;;;;;;CAYC,GACD,OAAO,SAASA,mBAAmB,EACjCC,IAAI,EACJC,UAAU,EACVC,WAAW,EACXC,YAAY,EACZC,WAAW,EACXC,GAAG,EACe;IAClB,OAAO;QACLL;QACA,YAAY;QACZ,SAAS;QACTM,UAAU;YACRN,MAAMG;YACN,SAAS;YACTE;QACF;QACA,GAAIH,cAAc;YAAEA;QAAY,IAAI,CAAC,CAAC;QACtC,GAAID,aAAa;YAAEA;QAAW,IAAI,CAAC,CAAC;QACpC,GAAIG,cAAc;YAAEA;QAAY,IAAI,CAAC,CAAC;IACxC;AACF"}

dist/modules/seo/buildSiteNavigationJsonLd.d.ts

@@ -0,0 +1,35 @@
+type NavItem = {
+    /** Visible label (e.g. 'Usługi'). */
+    name: string;
+    /** Absolute URL (e.g. 'https://example.com/pl/uslugi'). */
+    url: string;
+};
+/**
+ * Builds SiteNavigationElement JSON-LD (schema.org) from the main navigation —
+ * declares the site's primary nav as structured data. A weaker sitelinks signal
+ * than WebSite/breadcrumbs, but cheap: it tells Google which pages are the main
+ * navigation targets.
+ *
+ * Feed it the SAME nav items the header renders (from the panel/nav global), so
+ * the structured data matches the visible menu — not a separate hardcoded list.
+ *
+ *   import { buildSiteNavigationJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildSiteNavigationJsonLd(
+ *     navItems.map(i => ({ name: i.label, url: `${base}${i.href}` }))
+ *   )
+ *   <script type="application/ld+json" ... />
+ *
+ * Emit once (site-wide, root layout). Data from the nav source, never hardcoded.
+ * Returns null for empty nav.
+ */
+export declare function buildSiteNavigationJsonLd(items: NavItem[]): {
+    '@context': string;
+    '@type': string;
+    itemListElement: {
+        name: string;
+        '@type': string;
+        position: number;
+        url: string;
+    }[];
+} | null;
+export {};

dist/modules/seo/buildSiteNavigationJsonLd.js

@@ -0,0 +1,34 @@
+/**
+ * Builds SiteNavigationElement JSON-LD (schema.org) from the main navigation —
+ * declares the site's primary nav as structured data. A weaker sitelinks signal
+ * than WebSite/breadcrumbs, but cheap: it tells Google which pages are the main
+ * navigation targets.
+ *
+ * Feed it the SAME nav items the header renders (from the panel/nav global), so
+ * the structured data matches the visible menu — not a separate hardcoded list.
+ *
+ *   import { buildSiteNavigationJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildSiteNavigationJsonLd(
+ *     navItems.map(i => ({ name: i.label, url: `${base}${i.href}` }))
+ *   )
+ *   <script type="application/ld+json" ... />
+ *
+ * Emit once (site-wide, root layout). Data from the nav source, never hardcoded.
+ * Returns null for empty nav.
+ */ export function buildSiteNavigationJsonLd(items) {
+    if (!items || items.length === 0) {
+        return null;
+    }
+    return {
+        '@context': 'https://schema.org',
+        '@type': 'ItemList',
+        itemListElement: items.map((item, index)=>({
+                name: item.name,
+                '@type': 'SiteNavigationElement',
+                position: index + 1,
+                url: item.url
+            }))
+    };
+}
+
+//# sourceMappingURL=buildSiteNavigationJsonLd.js.map

dist/modules/seo/buildSiteNavigationJsonLd.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/modules/seo/buildSiteNavigationJsonLd.ts"],"sourcesContent":["type NavItem = {\n  /** Visible label (e.g. 'Usługi'). */\n  name: string\n  /** Absolute URL (e.g. 'https://example.com/pl/uslugi'). */\n  url: string\n}\n\n/**\n * Builds SiteNavigationElement JSON-LD (schema.org) from the main navigation —\n * declares the site's primary nav as structured data. A weaker sitelinks signal\n * than WebSite/breadcrumbs, but cheap: it tells Google which pages are the main\n * navigation targets.\n *\n * Feed it the SAME nav items the header renders (from the panel/nav global), so\n * the structured data matches the visible menu — not a separate hardcoded list.\n *\n *   import { buildSiteNavigationJsonLd } from '@intecion/ipal-kit'\n *   const jsonLd = buildSiteNavigationJsonLd(\n *     navItems.map(i => ({ name: i.label, url: `${base}${i.href}` }))\n *   )\n *   <script type=\"application/ld+json\" ... />\n *\n * Emit once (site-wide, root layout). Data from the nav source, never hardcoded.\n * Returns null for empty nav.\n */\nexport function buildSiteNavigationJsonLd(items: NavItem[]) {\n  if (!items || items.length === 0) {return null}\n\n  return {\n    '@context': 'https://schema.org',\n    '@type': 'ItemList',\n    itemListElement: items.map((item, index) => ({\n      name: item.name,\n      '@type': 'SiteNavigationElement',\n      position: index + 1,\n      url: item.url,\n    })),\n  }\n}\n"],"names":["buildSiteNavigationJsonLd","items","length","itemListElement","map","item","index","name","position","url"],"mappings":"AAOA;;;;;;;;;;;;;;;;;CAiBC,GACD,OAAO,SAASA,0BAA0BC,KAAgB;IACxD,IAAI,CAACA,SAASA,MAAMC,MAAM,KAAK,GAAG;QAAC,OAAO;IAAI;IAE9C,OAAO;QACL,YAAY;QACZ,SAAS;QACTC,iBAAiBF,MAAMG,GAAG,CAAC,CAACC,MAAMC,QAAW,CAAA;gBAC3CC,MAAMF,KAAKE,IAAI;gBACf,SAAS;gBACTC,UAAUF,QAAQ;gBAClBG,KAAKJ,KAAKI,GAAG;YACf,CAAA;IACF;AACF"}

dist/modules/seo/buildSitemapEntries.d.ts

@@ -1,6 +1,6 @@
 import type { BasePayload } from 'payload';
-import type { ContentOption } from '../content/index.js';
 import type { I18nConfig } from '../i18n/index.js';
+import type { ContentOption } from '../content/index.js';
 /**
  * One sitemap entry, shaped for Next's `app/sitemap.ts`.
  *
@@ -10,31 +10,31 @@ import type { I18nConfig } from '../i18n/index.js';
  * is the common, weaker kind.
  */
 export type SitemapEntry = {
+    url: string;
+    lastModified?: string | Date;
+    changeFrequency?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+    priority?: number;
     alternates?: {
         languages: Record<string, string>;
     };
-    changeFrequency?: 'always' | 'daily' | 'hourly' | 'monthly' | 'never' | 'weekly' | 'yearly';
-    lastModified?: Date | string;
-    priority?: number;
-    url: string;
 };
 type BuildSitemapArgs = {
+    payload: BasePayload;
+    config: I18nConfig;
     /** Absolute origin, e.g. 'https://example.com'. Required for valid sitemap URLs. */
     baseUrl: string;
-    changeFrequency?: SitemapEntry['changeFrequency'];
+    /** Pages collection slug. Defaults to 'pages'. */
-    config: I18nConfig;
+    pagesSlug?: string;
     /** Archive-backed collections, same value as the plugin option. */
     content?: ContentOption;
+    /** SiteSettings global slug. Defaults to 'site-settings'. */
+    settingsSlug?: string;
     /**
      * Slug of the page that is the site root (collapses to /{locale}).
      * Read from System Pages when omitted.
      */
     homeSlug?: string;
-    /** Pages collection slug. Defaults to 'pages'. */
+    changeFrequency?: SitemapEntry['changeFrequency'];
-    pagesSlug?: string;
-    payload: BasePayload;
-    /** SiteSettings global slug. Defaults to 'site-settings'. */
-    settingsSlug?: string;
 };
 /**
  * Collects every public URL — pages and archive entries — as sitemap entries
@@ -57,5 +57,5 @@ type BuildSitemapArgs = {
  * }
  * ```
  */
-export declare function buildSitemapEntries({ baseUrl, changeFrequency, config, content, homeSlug, pagesSlug, payload, settingsSlug, }: BuildSitemapArgs): Promise<SitemapEntry[]>;
+export declare function buildSitemapEntries({ payload, config, baseUrl, pagesSlug, content, settingsSlug, homeSlug, changeFrequency, }: BuildSitemapArgs): Promise<SitemapEntry[]>;
 export {};

dist/modules/seo/buildSitemapEntries.js

@@ -1,13 +1,31 @@
-import { archiveFieldName } from '../content/index.js';
+import { getLocalizedSlugs } from '../i18n/index.js';
-import { buildLocalizedPath, getLocalizedSlugs } from '../i18n/index.js';
+import { buildLocalizedPath } from '../i18n/index.js';
 import { buildHreflangAlternates } from './hreflang.js';
-/** Skip drafts and anything flagged noindex in the SEO tab. */ function isIndexable(doc) {
+import { archiveFieldName } from '../content/index.js';
-    if (doc._status && doc._status !== 'published') {
+/**
-        return false;
+ * Slugs that must never appear in the sitemap — error/system pages that exist as
+ * documents (e.g. a '404' page in the Pages collection) but should not be
+ * indexed. A sitemap should list only real, HTTP-200 content; a '/pl/404' entry
+ * is an audit finding. Matched against the slug in any locale.
+ */ const EXCLUDED_SITEMAP_SLUGS = new Set([
+    '404',
+    '500',
+    'not-found',
+    'error'
+]);
+/** True if the doc's slug (in any locale) is an excluded system/error slug. */ function hasExcludedSlug(slug) {
+    if (typeof slug === 'string') return EXCLUDED_SITEMAP_SLUGS.has(slug);
+    if (slug && typeof slug === 'object') {
+        for (const value of Object.values(slug)){
+            if (typeof value === 'string' && EXCLUDED_SITEMAP_SLUGS.has(value)) return true;
+        }
     }
-    if (doc.meta?.noindex) {
     return false;
 }
+/** Skip drafts, noindex, and system/error pages (404 etc.). */ function isIndexable(doc) {
+    if (doc._status && doc._status !== 'published') return false;
+    if (doc.meta?.noindex) return false;
+    if (hasExcludedSlug(doc.slug)) return false;
     return true;
 }
 /**
@@ -17,26 +35,24 @@ import { buildHreflangAlternates } from './hreflang.js';
  * every locale (including itself, per Google's guidance).
  */ function entryFor(doc, locale, config, baseUrl, homeSlug, prefix, changeFrequency) {
     const slugs = doc.slug && typeof doc.slug === 'object' ? getLocalizedSlugs({
-        config,
+        slugField: doc.slug,
-        slugField: doc.slug
+        config
     }) : {};
     const path = buildLocalizedPath({
+        slugs,
+        locale,
         config,
         homeSlug,
-        locale,
+        prefix
-        prefix,
-        slugs
     });
-    if (!path) {
+    if (!path) return null;
-        return null;
-    }
     const origin = baseUrl.replace(/\/$/, '');
     const languages = buildHreflangAlternates({
-        baseUrl,
+        slugs,
         config,
+        baseUrl,
         homeSlug,
-        prefix,
+        prefix
-        slugs
     });
     return {
         url: `${origin}${path}`,
@@ -73,15 +89,15 @@ import { buildHreflangAlternates } from './hreflang.js';
  *   })
  * }
  * ```
- */ export async function buildSitemapEntries({ baseUrl, changeFrequency = 'weekly', config, content, homeSlug, pagesSlug = 'pages', payload, settingsSlug = 'site-settings' }) {
+ */ export async function buildSitemapEntries({ payload, config, baseUrl, pagesSlug = 'pages', content, settingsSlug = 'site-settings', homeSlug, changeFrequency = 'weekly' }) {
     const locales = config.locales.map((l)=>l.code);
     const defaultLocale = config.defaultLocale;
     // Resolve homeSlug and archive prefixes from System Pages (read once, in all
     // locales so archive prefixes are available per language).
     const settings = await payload.findGlobal({
         slug: settingsSlug,
-        depth: 1,
+        locale: 'all',
-        locale: 'all'
+        depth: 1
     });
     const resolvedHomeSlug = homeSlug ?? extractSlugInLocale(settings.homepage, defaultLocale) ?? 'home';
     // Which collections to walk: pages (no prefix) + each content collection with
@@ -105,32 +121,24 @@ import { buildHreflangAlternates } from './hreflang.js';
         // alternates without re-querying per locale.
         const result = await payload.find({
             collection: collection.slug,
+            locale: 'all',
             depth: 0,
             limit: 0,
-            locale: 'all',
             pagination: false
         });
         for (const raw of result.docs){
-            if (!isIndexable(raw)) {
+            if (!isIndexable(raw)) continue;
-                continue;
-            }
             // Emit the entry under the default locale's URL; alternates cover the rest.
             const entry = entryFor(raw, defaultLocale, config, baseUrl, resolvedHomeSlug, collection.prefixSlugs, changeFrequency);
-            if (entry) {
+            if (entry) entries.push(entry);
-                entries.push(entry);
-            }
         }
     }
     return entries;
 }
 /** Pulls a slug string from a populated relationship in a specific locale. */ function extractSlugInLocale(rel, locale) {
-    if (!rel || typeof rel !== 'object') {
+    if (!rel || typeof rel !== 'object') return undefined;
-        return undefined;
-    }
     const slug = rel.slug;
-    if (typeof slug === 'string') {
+    if (typeof slug === 'string') return slug;
-        return slug;
-    }
     if (slug && typeof slug === 'object') {
         const v = slug[locale];
         return typeof v === 'string' ? v : undefined;
@@ -138,19 +146,13 @@ import { buildHreflangAlternates } from './hreflang.js';
     return undefined;
 }
 /** Builds a locale→slug map from a populated archive relationship. */ function slugMapAllLocales(rel, locales) {
-    if (!rel || typeof rel !== 'object') {
+    if (!rel || typeof rel !== 'object') return undefined;
-        return undefined;
-    }
     const slug = rel.slug;
-    if (!slug || typeof slug !== 'object') {
+    if (!slug || typeof slug !== 'object') return undefined;
-        return undefined;
-    }
     const map = {};
     for (const locale of locales){
         const v = slug[locale];
-        if (typeof v === 'string') {
+        if (typeof v === 'string') map[locale] = v;
-            map[locale] = v;
-        }
     }
     return Object.keys(map).length ? map : undefined;
 }

dist/modules/seo/buildWebSiteJsonLd.d.ts

@@ -0,0 +1,55 @@
+type SearchActionConfig = {
+    /**
+     * URL template for site search, with {search_term_string} placeholder.
+     * e.g. 'https://example.com/szukaj?q={search_term_string}'. Only include if
+     * the site actually HAS a working search page — a SearchAction pointing at a
+     * non-existent search does more harm than good.
+     */
+    target: string;
+};
+type WebSiteJsonLdArgs = {
+    /** Site name (from panel — siteName). */
+    name: string;
+    /**
+     * Optional site search. Enables the "sitelinks searchbox" — a search field
+     * Google may show under the brand result. Only pass when a real search page
+     * exists. Omit entirely otherwise.
+     */
+    search?: SearchActionConfig;
+    /** Absolute site URL (https://…). */
+    url: string;
+};
+/**
+ * Builds WebSite JSON-LD (schema.org). Two jobs:
+ *  - Declares the site + name (helps Google associate brand queries with the site).
+ *  - Optionally declares a SearchAction, which is what can produce the "sitelinks
+ *    searchbox" (a search field under the brand result in Google).
+ *
+ * IMPORTANT — sitelinks (the sub-links under a result) CANNOT be forced. No
+ * schema guarantees them; Google generates them algorithmically from site
+ * structure, internal links, clear titles, and ranking. This schema is a SIGNAL
+ * that improves the odds and can enable the searchbox — not a switch. Manage
+ * expectations accordingly (see docs/seo.md).
+ *
+ * Emit once in the ROOT layout (site-wide), from panel data:
+ *
+ *   import { buildWebSiteJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildWebSiteJsonLd({ name: settings.siteName, url: baseUrl })
+ *   <script type="application/ld+json"
+ *     dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }} />
+ */
+export declare function buildWebSiteJsonLd({ name, search, url }: WebSiteJsonLdArgs): {
+    potentialAction?: {
+        '@type': string;
+        'query-input': string;
+        target: {
+            '@type': string;
+            urlTemplate: string;
+        };
+    } | undefined;
+    name: string;
+    '@context': string;
+    '@type': string;
+    url: string;
+};
+export {};

dist/modules/seo/buildWebSiteJsonLd.js

@@ -0,0 +1,38 @@
+/**
+ * Builds WebSite JSON-LD (schema.org). Two jobs:
+ *  - Declares the site + name (helps Google associate brand queries with the site).
+ *  - Optionally declares a SearchAction, which is what can produce the "sitelinks
+ *    searchbox" (a search field under the brand result in Google).
+ *
+ * IMPORTANT — sitelinks (the sub-links under a result) CANNOT be forced. No
+ * schema guarantees them; Google generates them algorithmically from site
+ * structure, internal links, clear titles, and ranking. This schema is a SIGNAL
+ * that improves the odds and can enable the searchbox — not a switch. Manage
+ * expectations accordingly (see docs/seo.md).
+ *
+ * Emit once in the ROOT layout (site-wide), from panel data:
+ *
+ *   import { buildWebSiteJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildWebSiteJsonLd({ name: settings.siteName, url: baseUrl })
+ *   <script type="application/ld+json"
+ *     dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }} />
+ */ export function buildWebSiteJsonLd({ name, search, url }) {
+    return {
+        name,
+        '@context': 'https://schema.org',
+        '@type': 'WebSite',
+        url,
+        ...search ? {
+            potentialAction: {
+                '@type': 'SearchAction',
+                'query-input': 'required name=search_term_string',
+                target: {
+                    '@type': 'EntryPoint',
+                    urlTemplate: search.target
+                }
+            }
+        } : {}
+    };
+}
+
+//# sourceMappingURL=buildWebSiteJsonLd.js.map

dist/modules/seo/buildWebSiteJsonLd.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/modules/seo/buildWebSiteJsonLd.ts"],"sourcesContent":["type SearchActionConfig = {\n  /**\n   * URL template for site search, with {search_term_string} placeholder.\n   * e.g. 'https://example.com/szukaj?q={search_term_string}'. Only include if\n   * the site actually HAS a working search page — a SearchAction pointing at a\n   * non-existent search does more harm than good.\n   */\n  target: string\n}\n\ntype WebSiteJsonLdArgs = {\n  /** Site name (from panel — siteName). */\n  name: string\n  /**\n   * Optional site search. Enables the \"sitelinks searchbox\" — a search field\n   * Google may show under the brand result. Only pass when a real search page\n   * exists. Omit entirely otherwise.\n   */\n  search?: SearchActionConfig\n  /** Absolute site URL (https://…). */\n  url: string\n}\n\n/**\n * Builds WebSite JSON-LD (schema.org). Two jobs:\n *  - Declares the site + name (helps Google associate brand queries with the site).\n *  - Optionally declares a SearchAction, which is what can produce the \"sitelinks\n *    searchbox\" (a search field under the brand result in Google).\n *\n * IMPORTANT — sitelinks (the sub-links under a result) CANNOT be forced. No\n * schema guarantees them; Google generates them algorithmically from site\n * structure, internal links, clear titles, and ranking. This schema is a SIGNAL\n * that improves the odds and can enable the searchbox — not a switch. Manage\n * expectations accordingly (see docs/seo.md).\n *\n * Emit once in the ROOT layout (site-wide), from panel data:\n *\n *   import { buildWebSiteJsonLd } from '@intecion/ipal-kit'\n *   const jsonLd = buildWebSiteJsonLd({ name: settings.siteName, url: baseUrl })\n *   <script type=\"application/ld+json\"\n *     dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }} />\n */\nexport function buildWebSiteJsonLd({ name, search, url }: WebSiteJsonLdArgs) {\n  return {\n    name,\n    '@context': 'https://schema.org',\n    '@type': 'WebSite',\n    url,\n    ...(search\n      ? {\n          potentialAction: {\n            '@type': 'SearchAction',\n            'query-input': 'required name=search_term_string',\n            target: {\n              '@type': 'EntryPoint',\n              urlTemplate: search.target,\n            },\n          },\n        }\n      : {}),\n  }\n}\n"],"names":["buildWebSiteJsonLd","name","search","url","potentialAction","target","urlTemplate"],"mappings":"AAuBA;;;;;;;;;;;;;;;;;;CAkBC,GACD,OAAO,SAASA,mBAAmB,EAAEC,IAAI,EAAEC,MAAM,EAAEC,GAAG,EAAqB;IACzE,OAAO;QACLF;QACA,YAAY;QACZ,SAAS;QACTE;QACA,GAAID,SACA;YACEE,iBAAiB;gBACf,SAAS;gBACT,eAAe;gBACfC,QAAQ;oBACN,SAAS;oBACTC,aAAaJ,OAAOG,MAAM;gBAC5B;YACF;QACF,IACA,CAAC,CAAC;IACR;AACF"}

dist/modules/seo/createPageMetadata.js

@@ -90,6 +90,7 @@ import { slugsAcrossLocales } from './slugsAcrossLocales.js';
             ...base,
             imageUrl: resolveOgImage(doc),
             meta: doc.meta,
+            pageTitle: doc.title,
             prefix,
             query,
             slugs

dist/modules/seo/hreflang.d.ts

@@ -15,20 +15,28 @@ type BuildHreflangArgs = {
     slugs: LocalizedSlugs;
 };
 /**
- * Builds a map of locale → URL for hreflang alternate links, suitable for
  * Next.js Metadata `alternates.languages`.
  *
  * Bridges SEO and i18n: for each configured locale that the document has a
  * slug in, it produces the locale-aware path (via buildLocalizedPath),
  * optionally prefixed with an absolute origin.
  *
+ * Also emits `x-default` pointing at the default locale — the version Google
+ * serves when the user's language/region matches no hreflang, and the fallback
+ * when the root ('/') redirect is ambiguous (Googlebot with no/foreign
+ * Accept-Language).
+ *
  * @example
  * buildHreflangAlternates({
  *   slugs: { pl: 'o-nas', en: 'about' },
  *   config,
  *   baseUrl: 'https://example.com',
  * })
- * // → { pl: 'https://example.com/pl/o-nas', en: 'https://example.com/en/about' }
+ * // → {
+ * //   pl: 'https://example.com/pl/o-nas',
+ * //   en: 'https://example.com/en/about',
+ * //   'x-default': 'https://example.com/pl/o-nas',
+ * // }
  */
 export declare function buildHreflangAlternates({ baseUrl, config, homeSlug, prefix, slugs, }: BuildHreflangArgs): Record<string, string>;
 export {};

dist/modules/seo/hreflang.js

@@ -1,19 +1,27 @@
-import { buildLocalizedPath, getLocaleCodes } from '../i18n/index.js';
+import { buildLocalizedPath, getDefaultLocale, getLocaleCodes } from '../i18n/index.js';
 /**
- * Builds a map of locale → URL for hreflang alternate links, suitable for
  * Next.js Metadata `alternates.languages`.
  *
  * Bridges SEO and i18n: for each configured locale that the document has a
  * slug in, it produces the locale-aware path (via buildLocalizedPath),
  * optionally prefixed with an absolute origin.
  *
+ * Also emits `x-default` pointing at the default locale — the version Google
+ * serves when the user's language/region matches no hreflang, and the fallback
+ * when the root ('/') redirect is ambiguous (Googlebot with no/foreign
+ * Accept-Language).
+ *
  * @example
  * buildHreflangAlternates({
  *   slugs: { pl: 'o-nas', en: 'about' },
  *   config,
  *   baseUrl: 'https://example.com',
  * })
- * // → { pl: 'https://example.com/pl/o-nas', en: 'https://example.com/en/about' }
+ * // → {
+ * //   pl: 'https://example.com/pl/o-nas',
+ * //   en: 'https://example.com/en/about',
+ * //   'x-default': 'https://example.com/pl/o-nas',
+ * // }
  */ export function buildHreflangAlternates({ baseUrl, config, homeSlug = 'home', prefix, slugs }) {
     const origin = baseUrl?.replace(/\/$/, '') ?? '';
     const alternates = {};
@@ -29,6 +37,15 @@ import { buildLocalizedPath, getLocaleCodes } from '../i18n/index.js';
             alternates[locale] = `${origin}${path}`;
         }
     }
+    // x-default: the version Google serves when the user's language/region doesn't
+    // match any hreflang — and, crucially here, the fallback when the root ('/')
+    // redirect is ambiguous (Googlebot with no/foreign Accept-Language). Point it
+    // at the default locale (the primary market) so search shows that version by
+    // default instead of guessing. Only set when the default locale has a URL.
+    const defaultLocalePath = alternates[getDefaultLocale(config)];
+    if (defaultLocalePath) {
+        alternates['x-default'] = defaultLocalePath;
+    }
     return alternates;
 }
 

dist/modules/seo/hreflang.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/modules/seo/hreflang.ts"],"sourcesContent":["import type { I18nConfig, LocalizedSlugs } from '../i18n/index.js'\n\nimport { buildLocalizedPath, getLocaleCodes } from '../i18n/index.js'\n\ntype BuildHreflangArgs = {\n  /** Absolute site origin, e.g. 'https://example.com'. Omit for relative paths. */\n  baseUrl?: string\n  config: I18nConfig\n  /** Home slug that collapses to the locale root. Defaults to 'home'. */\n  homeSlug?: string\n  /**\n   * Localized segment the document lives under (an archive page's slugs),\n   * e.g. { pl: 'artykuly', en: 'articles' }. Locales missing from the prefix\n   * are omitted — an entry with no archive in that language has no URL there.\n   */\n  prefix?: LocalizedSlugs\n  /** slug per locale for the current document, e.g. { pl: 'o-nas', en: 'about' } */\n  slugs: LocalizedSlugs\n}\n\n/**\n * Builds a map of locale → URL for hreflang alternate links, suitable for\n * Next.js Metadata `alternates.languages`.\n *\n * Bridges SEO and i18n: for each configured locale that the document has a\n * slug in, it produces the locale-aware path (via buildLocalizedPath),\n * optionally prefixed with an absolute origin.\n *\n * @example\n * buildHreflangAlternates({\n *   slugs: { pl: 'o-nas', en: 'about' },\n *   config,\n *   baseUrl: 'https://example.com',\n * })\n * // → { pl: 'https://example.com/pl/o-nas', en: 'https://example.com/en/about' }\n */\nexport function buildHreflangAlternates({\n  baseUrl,\n  config,\n  homeSlug = 'home',\n  prefix,\n  slugs,\n}: BuildHreflangArgs): Record<string, string> {\n  const origin = baseUrl?.replace(/\\/$/, '') ?? ''\n  const alternates: Record<string, string> = {}\n\n  for (const locale of getLocaleCodes(config)) {\n    const path = buildLocalizedPath({ config, homeSlug, locale, prefix, slugs })\n    if (path) {\n      alternates[locale] = `${origin}${path}`\n    }\n  }\n\n  return alternates\n}\n"],"names":["buildLocalizedPath","getLocaleCodes","buildHreflangAlternates","baseUrl","config","homeSlug","prefix","slugs","origin","replace","alternates","locale","path"],"mappings":"AAEA,SAASA,kBAAkB,EAAEC,cAAc,QAAQ,mBAAkB;AAkBrE;;;;;;;;;;;;;;;CAeC,GACD,OAAO,SAASC,wBAAwB,EACtCC,OAAO,EACPC,MAAM,EACNC,WAAW,MAAM,EACjBC,MAAM,EACNC,KAAK,EACa;IAClB,MAAMC,SAASL,SAASM,QAAQ,OAAO,OAAO;IAC9C,MAAMC,aAAqC,CAAC;IAE5C,KAAK,MAAMC,UAAUV,eAAeG,QAAS;QAC3C,MAAMQ,OAAOZ,mBAAmB;YAAEI;YAAQC;YAAUM;YAAQL;YAAQC;QAAM;QAC1E,IAAIK,MAAM;YACRF,UAAU,CAACC,OAAO,GAAG,GAAGH,SAASI,MAAM;QACzC;IACF;IAEA,OAAOF;AACT"}
+{"version":3,"sources":["../../../src/modules/seo/hreflang.ts"],"sourcesContent":["import type { I18nConfig, LocalizedSlugs } from '../i18n/index.js'\n\nimport { buildLocalizedPath, getDefaultLocale, getLocaleCodes } from '../i18n/index.js'\n\ntype BuildHreflangArgs = {\n  /** Absolute site origin, e.g. 'https://example.com'. Omit for relative paths. */\n  baseUrl?: string\n  config: I18nConfig\n  /** Home slug that collapses to the locale root. Defaults to 'home'. */\n  homeSlug?: string\n  /**\n   * Localized segment the document lives under (an archive page's slugs),\n   * e.g. { pl: 'artykuly', en: 'articles' }. Locales missing from the prefix\n   * are omitted — an entry with no archive in that language has no URL there.\n   */\n  prefix?: LocalizedSlugs\n  /** slug per locale for the current document, e.g. { pl: 'o-nas', en: 'about' } */\n  slugs: LocalizedSlugs\n}\n\n/**\n * Next.js Metadata `alternates.languages`.\n *\n * Bridges SEO and i18n: for each configured locale that the document has a\n * slug in, it produces the locale-aware path (via buildLocalizedPath),\n * optionally prefixed with an absolute origin.\n *\n * Also emits `x-default` pointing at the default locale — the version Google\n * serves when the user's language/region matches no hreflang, and the fallback\n * when the root ('/') redirect is ambiguous (Googlebot with no/foreign\n * Accept-Language).\n *\n * @example\n * buildHreflangAlternates({\n *   slugs: { pl: 'o-nas', en: 'about' },\n *   config,\n *   baseUrl: 'https://example.com',\n * })\n * // → {\n * //   pl: 'https://example.com/pl/o-nas',\n * //   en: 'https://example.com/en/about',\n * //   'x-default': 'https://example.com/pl/o-nas',\n * // }\n */\nexport function buildHreflangAlternates({\n  baseUrl,\n  config,\n  homeSlug = 'home',\n  prefix,\n  slugs,\n}: BuildHreflangArgs): Record<string, string> {\n  const origin = baseUrl?.replace(/\\/$/, '') ?? ''\n  const alternates: Record<string, string> = {}\n\n  for (const locale of getLocaleCodes(config)) {\n    const path = buildLocalizedPath({ config, homeSlug, locale, prefix, slugs })\n    if (path) {\n      alternates[locale] = `${origin}${path}`\n    }\n  }\n\n  // x-default: the version Google serves when the user's language/region doesn't\n  // match any hreflang — and, crucially here, the fallback when the root ('/')\n  // redirect is ambiguous (Googlebot with no/foreign Accept-Language). Point it\n  // at the default locale (the primary market) so search shows that version by\n  // default instead of guessing. Only set when the default locale has a URL.\n  const defaultLocalePath = alternates[getDefaultLocale(config)]\n  if (defaultLocalePath) {\n    alternates['x-default'] = defaultLocalePath\n  }\n\n  return alternates\n}\n"],"names":["buildLocalizedPath","getDefaultLocale","getLocaleCodes","buildHreflangAlternates","baseUrl","config","homeSlug","prefix","slugs","origin","replace","alternates","locale","path","defaultLocalePath"],"mappings":"AAEA,SAASA,kBAAkB,EAAEC,gBAAgB,EAAEC,cAAc,QAAQ,mBAAkB;AAkBvF;;;;;;;;;;;;;;;;;;;;;;;CAuBC,GACD,OAAO,SAASC,wBAAwB,EACtCC,OAAO,EACPC,MAAM,EACNC,WAAW,MAAM,EACjBC,MAAM,EACNC,KAAK,EACa;IAClB,MAAMC,SAASL,SAASM,QAAQ,OAAO,OAAO;IAC9C,MAAMC,aAAqC,CAAC;IAE5C,KAAK,MAAMC,UAAUV,eAAeG,QAAS;QAC3C,MAAMQ,OAAOb,mBAAmB;YAAEK;YAAQC;YAAUM;YAAQL;YAAQC;QAAM;QAC1E,IAAIK,MAAM;YACRF,UAAU,CAACC,OAAO,GAAG,GAAGH,SAASI,MAAM;QACzC;IACF;IAEA,+EAA+E;IAC/E,6EAA6E;IAC7E,8EAA8E;IAC9E,6EAA6E;IAC7E,2EAA2E;IAC3E,MAAMC,oBAAoBH,UAAU,CAACV,iBAAiBI,QAAQ;IAC9D,IAAIS,mBAAmB;QACrBH,UAAU,CAAC,YAAY,GAAGG;IAC5B;IAEA,OAAOH;AACT"}

dist/modules/seo/index.d.ts

@@ -1,11 +1,19 @@
 export { buildAutoFillMetaHook } from './autoFillMeta.js';
 export type { AutoFillMapping } from './autoFillMeta.js';
+export { buildBreadcrumbJsonLd } from './buildBreadcrumbJsonLd.js';
+export { buildFaqJsonLd } from './buildFaqJsonLd.js';
+export { buildIconsMetadata } from './buildIconsMetadata.js';
+export { buildLocalBusinessJsonLd } from './buildLocalBusinessJsonLd.js';
 export { buildMetadata } from './buildMetadata.js';
 export type { PageMetadata } from './buildMetadata.js';
+export { buildOrganizationJsonLd } from './buildOrganizationJsonLd.js';
 export { buildRobots } from './buildRobots.js';
 export type { RobotsRules } from './buildRobots.js';
+export { buildServiceJsonLd } from './buildServiceJsonLd.js';
 export { buildSitemapEntries } from './buildSitemapEntries.js';
 export type { SitemapEntry } from './buildSitemapEntries.js';
+export { buildSiteNavigationJsonLd } from './buildSiteNavigationJsonLd.js';
+export { buildWebSiteJsonLd } from './buildWebSiteJsonLd.js';
 export { composeTitle } from './composeTitle.js';
 export type { TitleOrder } from './composeTitle.js';
 export { createMetadataGenerator } from './createMetadataGenerator.js';
@@ -18,3 +26,4 @@ export type { SiteMetaConfig } from './readSiteMetaConfig.js';
 export { buildSeoPlugin } from './seoPluginConfig.js';
 export { slugsAcrossLocales } from './slugsAcrossLocales.js';
 export type { SeoMeta, SeoOption } from './types.js';
+export { validateFaviconField } from './validateFavicon.js';

dist/modules/seo/index.js

@@ -1,7 +1,15 @@
 export { buildAutoFillMetaHook } from './autoFillMeta.js';
+export { buildBreadcrumbJsonLd } from './buildBreadcrumbJsonLd.js';
+export { buildFaqJsonLd } from './buildFaqJsonLd.js';
+export { buildIconsMetadata } from './buildIconsMetadata.js';
+export { buildLocalBusinessJsonLd } from './buildLocalBusinessJsonLd.js';
 export { buildMetadata } from './buildMetadata.js';
+export { buildOrganizationJsonLd } from './buildOrganizationJsonLd.js';
 export { buildRobots } from './buildRobots.js';
+export { buildServiceJsonLd } from './buildServiceJsonLd.js';
 export { buildSitemapEntries } from './buildSitemapEntries.js';
+export { buildSiteNavigationJsonLd } from './buildSiteNavigationJsonLd.js';
+export { buildWebSiteJsonLd } from './buildWebSiteJsonLd.js';
 export { composeTitle } from './composeTitle.js';
 export { createMetadataGenerator } from './createMetadataGenerator.js';
 export { createPageMetadata } from './createPageMetadata.js';
@@ -11,5 +19,6 @@ export { injectSeoTabs } from './injectSeoTabs.js';
 export { readSiteMetaConfig } from './readSiteMetaConfig.js';
 export { buildSeoPlugin } from './seoPluginConfig.js';
 export { slugsAcrossLocales } from './slugsAcrossLocales.js';
+export { validateFaviconField } from './validateFavicon.js';
 
 //# sourceMappingURL=index.js.map

dist/modules/seo/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/modules/seo/index.ts"],"sourcesContent":["export { buildAutoFillMetaHook } from './autoFillMeta.js'\nexport type { AutoFillMapping } from './autoFillMeta.js'\nexport { buildMetadata } from './buildMetadata.js'\nexport type { PageMetadata } from './buildMetadata.js'\nexport { buildRobots } from './buildRobots.js'\nexport type { RobotsRules } from './buildRobots.js'\nexport { buildSitemapEntries } from './buildSitemapEntries.js'\nexport type { SitemapEntry } from './buildSitemapEntries.js'\nexport { composeTitle } from './composeTitle.js'\nexport type { TitleOrder } from './composeTitle.js'\nexport { createMetadataGenerator } from './createMetadataGenerator.js'\nexport { createPageMetadata } from './createPageMetadata.js'\nexport { buildHreflangAlternates } from './hreflang.js'\nexport { injectAutoFillMeta } from './injectAutoFillMeta.js'\nexport { injectSeoTabs } from './injectSeoTabs.js'\nexport { readSiteMetaConfig } from './readSiteMetaConfig.js'\nexport type { SiteMetaConfig } from './readSiteMetaConfig.js'\nexport { buildSeoPlugin } from './seoPluginConfig.js'\nexport { slugsAcrossLocales } from './slugsAcrossLocales.js'\nexport type { SeoMeta, SeoOption } from './types.js'\n"],"names":["buildAutoFillMetaHook","buildMetadata","buildRobots","buildSitemapEntries","composeTitle","createMetadataGenerator","createPageMetadata","buildHreflangAlternates","injectAutoFillMeta","injectSeoTabs","readSiteMetaConfig","buildSeoPlugin","slugsAcrossLocales"],"mappings":"AAAA,SAASA,qBAAqB,QAAQ,oBAAmB;AAEzD,SAASC,aAAa,QAAQ,qBAAoB;AAElD,SAASC,WAAW,QAAQ,mBAAkB;AAE9C,SAASC,mBAAmB,QAAQ,2BAA0B;AAE9D,SAASC,YAAY,QAAQ,oBAAmB;AAEhD,SAASC,uBAAuB,QAAQ,+BAA8B;AACtE,SAASC,kBAAkB,QAAQ,0BAAyB;AAC5D,SAASC,uBAAuB,QAAQ,gBAAe;AACvD,SAASC,kBAAkB,QAAQ,0BAAyB;AAC5D,SAASC,aAAa,QAAQ,qBAAoB;AAClD,SAASC,kBAAkB,QAAQ,0BAAyB;AAE5D,SAASC,cAAc,QAAQ,uBAAsB;AACrD,SAASC,kBAAkB,QAAQ,0BAAyB"}
+{"version":3,"sources":["../../../src/modules/seo/index.ts"],"sourcesContent":["export { buildAutoFillMetaHook } from './autoFillMeta.js'\nexport type { AutoFillMapping } from './autoFillMeta.js'\nexport { buildBreadcrumbJsonLd } from './buildBreadcrumbJsonLd.js'\nexport { buildFaqJsonLd } from './buildFaqJsonLd.js'\nexport { buildIconsMetadata } from './buildIconsMetadata.js'\nexport { buildLocalBusinessJsonLd } from './buildLocalBusinessJsonLd.js'\nexport { buildMetadata } from './buildMetadata.js'\nexport type { PageMetadata } from './buildMetadata.js'\nexport { buildOrganizationJsonLd } from './buildOrganizationJsonLd.js'\nexport { buildRobots } from './buildRobots.js'\nexport type { RobotsRules } from './buildRobots.js'\nexport { buildServiceJsonLd } from './buildServiceJsonLd.js'\nexport { buildSitemapEntries } from './buildSitemapEntries.js'\nexport type { SitemapEntry } from './buildSitemapEntries.js'\nexport { buildSiteNavigationJsonLd } from './buildSiteNavigationJsonLd.js'\nexport { buildWebSiteJsonLd } from './buildWebSiteJsonLd.js'\nexport { composeTitle } from './composeTitle.js'\nexport type { TitleOrder } from './composeTitle.js'\nexport { createMetadataGenerator } from './createMetadataGenerator.js'\nexport { createPageMetadata } from './createPageMetadata.js'\nexport { buildHreflangAlternates } from './hreflang.js'\nexport { injectAutoFillMeta } from './injectAutoFillMeta.js'\nexport { injectSeoTabs } from './injectSeoTabs.js'\nexport { readSiteMetaConfig } from './readSiteMetaConfig.js'\nexport type { SiteMetaConfig } from './readSiteMetaConfig.js'\nexport { buildSeoPlugin } from './seoPluginConfig.js'\nexport { slugsAcrossLocales } from './slugsAcrossLocales.js'\nexport type { SeoMeta, SeoOption } from './types.js'\nexport { validateFaviconField } from './validateFavicon.js'\n"],"names":["buildAutoFillMetaHook","buildBreadcrumbJsonLd","buildFaqJsonLd","buildIconsMetadata","buildLocalBusinessJsonLd","buildMetadata","buildOrganizationJsonLd","buildRobots","buildServiceJsonLd","buildSitemapEntries","buildSiteNavigationJsonLd","buildWebSiteJsonLd","composeTitle","createMetadataGenerator","createPageMetadata","buildHreflangAlternates","injectAutoFillMeta","injectSeoTabs","readSiteMetaConfig","buildSeoPlugin","slugsAcrossLocales","validateFaviconField"],"mappings":"AAAA,SAASA,qBAAqB,QAAQ,oBAAmB;AAEzD,SAASC,qBAAqB,QAAQ,6BAA4B;AAClE,SAASC,cAAc,QAAQ,sBAAqB;AACpD,SAASC,kBAAkB,QAAQ,0BAAyB;AAC5D,SAASC,wBAAwB,QAAQ,gCAA+B;AACxE,SAASC,aAAa,QAAQ,qBAAoB;AAElD,SAASC,uBAAuB,QAAQ,+BAA8B;AACtE,SAASC,WAAW,QAAQ,mBAAkB;AAE9C,SAASC,kBAAkB,QAAQ,0BAAyB;AAC5D,SAASC,mBAAmB,QAAQ,2BAA0B;AAE9D,SAASC,yBAAyB,QAAQ,iCAAgC;AAC1E,SAASC,kBAAkB,QAAQ,0BAAyB;AAC5D,SAASC,YAAY,QAAQ,oBAAmB;AAEhD,SAASC,uBAAuB,QAAQ,+BAA8B;AACtE,SAASC,kBAAkB,QAAQ,0BAAyB;AAC5D,SAASC,uBAAuB,QAAQ,gBAAe;AACvD,SAASC,kBAAkB,QAAQ,0BAAyB;AAC5D,SAASC,aAAa,QAAQ,qBAAoB;AAClD,SAASC,kBAAkB,QAAQ,0BAAyB;AAE5D,SAASC,cAAc,QAAQ,uBAAsB;AACrD,SAASC,kBAAkB,QAAQ,0BAAyB;AAE5D,SAASC,oBAAoB,QAAQ,uBAAsB"}

dist/modules/seo/types.d.ts

@@ -34,6 +34,7 @@ export type SeoOption = {
 export type SeoMeta = {
     description?: null | string;
     image?: unknown;
+    noindex?: boolean | null;
     title?: null | string;
     /** When set, used as the whole title — no site name, no separator. */
     titleOverride?: null | string;

dist/modules/seo/types.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/modules/seo/types.ts"],"sourcesContent":["import type { Field } from 'payload'\n\nimport type { AutoFillMapping } from './autoFillMeta.js'\n\n/**\n * SEO configuration.\n *\n * The plugin wires @payloadcms/plugin-seo into the client's config and adds\n * locale-aware metadata helpers on top. Collections come from options because\n * the plugin doesn't own the client's content collections (e.g. Pages).\n */\nexport type SeoOption = {\n  /**\n   * Auto-fill empty meta from document fields on save. Defaults to the website\n   * template mapping (title → meta.title). Set to false to disable.\n   */\n  autoFill?: AutoFillMapping | false\n  /** Collection slugs that receive SEO meta fields, e.g. ['pages', 'posts']. */\n  collections: string[]\n  /** Extra fields appended to the SEO group in the admin. */\n  fields?: Field[]\n  /** Optional: customize how meta descriptions are generated. */\n  generateDescription?: (args: { doc: Record<string, unknown> }) => string\n  /** Optional: customize how meta titles are generated in the admin preview. */\n  generateTitle?: (args: { doc: Record<string, unknown> }) => string\n}\n\n/**\n * Minimal shape of the SEO meta group as stored on a document by\n * @payloadcms/plugin-seo. The client's generated types are richer; helpers\n * depend only on this.\n */\nexport type SeoMeta = {\n  description?: null | string\n  image?: unknown\n  title?: null | string\n  /** When set, used as the whole title — no site name, no separator. */\n  titleOverride?: null | string\n}\n"],"names":[],"mappings":"AA2BA;;;;CAIC,GACD,WAMC"}
+{"version":3,"sources":["../../../src/modules/seo/types.ts"],"sourcesContent":["import type { Field } from 'payload'\n\nimport type { AutoFillMapping } from './autoFillMeta.js'\n\n/**\n * SEO configuration.\n *\n * The plugin wires @payloadcms/plugin-seo into the client's config and adds\n * locale-aware metadata helpers on top. Collections come from options because\n * the plugin doesn't own the client's content collections (e.g. Pages).\n */\nexport type SeoOption = {\n  /**\n   * Auto-fill empty meta from document fields on save. Defaults to the website\n   * template mapping (title → meta.title). Set to false to disable.\n   */\n  autoFill?: AutoFillMapping | false\n  /** Collection slugs that receive SEO meta fields, e.g. ['pages', 'posts']. */\n  collections: string[]\n  /** Extra fields appended to the SEO group in the admin. */\n  fields?: Field[]\n  /** Optional: customize how meta descriptions are generated. */\n  generateDescription?: (args: { doc: Record<string, unknown> }) => string\n  /** Optional: customize how meta titles are generated in the admin preview. */\n  generateTitle?: (args: { doc: Record<string, unknown> }) => string\n}\n\n/**\n * Minimal shape of the SEO meta group as stored on a document by\n * @payloadcms/plugin-seo. The client's generated types are richer; helpers\n * depend only on this.\n */\nexport type SeoMeta = {\n  description?: null | string\n  image?: unknown\n  noindex?: boolean | null\n  title?: null | string\n  /** When set, used as the whole title — no site name, no separator. */\n  titleOverride?: null | string\n}\n"],"names":[],"mappings":"AA2BA;;;;CAIC,GACD,WAOC"}

dist/modules/seo/validateFavicon.d.ts

@@ -0,0 +1,15 @@
+import type { FieldHook } from 'payload';
+/**
+ * Field validation for the favicon upload: Google rejects favicons under 48×48,
+ * so warn the editor at save time if the uploaded icon is too small or not
+ * square. This ENFORCES the requirement instead of silently shipping a favicon
+ * Google won't display.
+ *
+ * Attach to the favicon field's validate (or as a beforeValidate hook on the
+ * Media relationship). Non-blocking by default — returns a warning string that
+ * Payload surfaces; make it throw if you want a hard block.
+ *
+ * Note: dimensions come from the related Media doc (Payload stores width/height
+ * for image uploads), so this checks the resolved upload, not the raw file.
+ */
+export declare const validateFaviconField: FieldHook;

dist/modules/seo/validateFavicon.js

@@ -0,0 +1,44 @@
+/**
+ * Field validation for the favicon upload: Google rejects favicons under 48×48,
+ * so warn the editor at save time if the uploaded icon is too small or not
+ * square. This ENFORCES the requirement instead of silently shipping a favicon
+ * Google won't display.
+ *
+ * Attach to the favicon field's validate (or as a beforeValidate hook on the
+ * Media relationship). Non-blocking by default — returns a warning string that
+ * Payload surfaces; make it throw if you want a hard block.
+ *
+ * Note: dimensions come from the related Media doc (Payload stores width/height
+ * for image uploads), so this checks the resolved upload, not the raw file.
+ */ export const validateFaviconField = async ({ req, value })=>{
+    if (!value) {
+        return value;
+    } // no favicon set → nothing to validate (optional field)
+    try {
+        const media = await req.payload.findByID({
+            id: typeof value === 'object' ? value.id : value,
+            collection: 'media',
+            depth: 0
+        });
+        const width = media.width;
+        const height = media.height;
+        const mimeType = media.mimeType;
+        // SVG scales infinitely — skip size checks.
+        if (mimeType === 'image/svg+xml') {
+            return value;
+        }
+        if (typeof width === 'number' && typeof height === 'number') {
+            if (width < 48 || height < 48) {
+                req.payload.logger.warn(`[ipal] Favicon is ${width}×${height}px. Google requires ≥48×48 to ` + `display it in search results. Upload a larger square icon (96 or 192px).`);
+            }
+            if (width !== height) {
+                req.payload.logger.warn(`[ipal] Favicon is not square (${width}×${height}). Use a square icon ` + `so it isn't cropped in the browser tab or search results.`);
+            }
+        }
+    } catch  {
+    // Media lookup failed — don't block the save over a validation warning.
+    }
+    return value;
+};
+
+//# sourceMappingURL=validateFavicon.js.map

dist/modules/seo/validateFavicon.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/modules/seo/validateFavicon.ts"],"sourcesContent":["import type { FieldHook } from 'payload'\n\n/**\n * Field validation for the favicon upload: Google rejects favicons under 48×48,\n * so warn the editor at save time if the uploaded icon is too small or not\n * square. This ENFORCES the requirement instead of silently shipping a favicon\n * Google won't display.\n *\n * Attach to the favicon field's validate (or as a beforeValidate hook on the\n * Media relationship). Non-blocking by default — returns a warning string that\n * Payload surfaces; make it throw if you want a hard block.\n *\n * Note: dimensions come from the related Media doc (Payload stores width/height\n * for image uploads), so this checks the resolved upload, not the raw file.\n */\nexport const validateFaviconField: FieldHook = async ({ req, value }) => {\n  if (!value) {return value} // no favicon set → nothing to validate (optional field)\n\n  try {\n    const media = await req.payload.findByID({\n      id: typeof value === 'object' ? (value as { id: string }).id : value,\n      collection: 'media',\n      depth: 0,\n    })\n\n    const width = (media as { width?: number }).width\n    const height = (media as { height?: number }).height\n    const mimeType = (media as { mimeType?: string }).mimeType\n\n    // SVG scales infinitely — skip size checks.\n    if (mimeType === 'image/svg+xml') {return value}\n\n    if (typeof width === 'number' && typeof height === 'number') {\n      if (width < 48 || height < 48) {\n        req.payload.logger.warn(\n          `[ipal] Favicon is ${width}×${height}px. Google requires ≥48×48 to ` +\n            `display it in search results. Upload a larger square icon (96 or 192px).`,\n        )\n      }\n      if (width !== height) {\n        req.payload.logger.warn(\n          `[ipal] Favicon is not square (${width}×${height}). Use a square icon ` +\n            `so it isn't cropped in the browser tab or search results.`,\n        )\n      }\n    }\n  } catch {\n    // Media lookup failed — don't block the save over a validation warning.\n  }\n\n  return value\n}\n"],"names":["validateFaviconField","req","value","media","payload","findByID","id","collection","depth","width","height","mimeType","logger","warn"],"mappings":"AAEA;;;;;;;;;;;;CAYC,GACD,OAAO,MAAMA,uBAAkC,OAAO,EAAEC,GAAG,EAAEC,KAAK,EAAE;IAClE,IAAI,CAACA,OAAO;QAAC,OAAOA;IAAK,EAAE,wDAAwD;IAEnF,IAAI;QACF,MAAMC,QAAQ,MAAMF,IAAIG,OAAO,CAACC,QAAQ,CAAC;YACvCC,IAAI,OAAOJ,UAAU,WAAW,AAACA,MAAyBI,EAAE,GAAGJ;YAC/DK,YAAY;YACZC,OAAO;QACT;QAEA,MAAMC,QAAQ,AAACN,MAA6BM,KAAK;QACjD,MAAMC,SAAS,AAACP,MAA8BO,MAAM;QACpD,MAAMC,WAAW,AAACR,MAAgCQ,QAAQ;QAE1D,4CAA4C;QAC5C,IAAIA,aAAa,iBAAiB;YAAC,OAAOT;QAAK;QAE/C,IAAI,OAAOO,UAAU,YAAY,OAAOC,WAAW,UAAU;YAC3D,IAAID,QAAQ,MAAMC,SAAS,IAAI;gBAC7BT,IAAIG,OAAO,CAACQ,MAAM,CAACC,IAAI,CACrB,CAAC,kBAAkB,EAAEJ,MAAM,CAAC,EAAEC,OAAO,8BAA8B,CAAC,GAClE,CAAC,wEAAwE,CAAC;YAEhF;YACA,IAAID,UAAUC,QAAQ;gBACpBT,IAAIG,OAAO,CAACQ,MAAM,CAACC,IAAI,CACrB,CAAC,8BAA8B,EAAEJ,MAAM,CAAC,EAAEC,OAAO,qBAAqB,CAAC,GACrE,CAAC,yDAAyD,CAAC;YAEjE;QACF;IACF,EAAE,OAAM;IACN,wEAAwE;IAC1E;IAEA,OAAOR;AACT,EAAC"}

dist/modules/storage/MediaPreconnect.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Emits <link rel="preconnect"> + <link rel="dns-prefetch"> for the media CDN
+ * domain (R2_PUBLIC_URL), so the browser opens the TLS/DNS connection to the
+ * media host early — before it hits the first <img>. Saves ~150–300ms on the
+ * first image load.
+ *
+ * Reads the domain from R2_PUBLIC_URL (the same env var buildR2Storage uses),
+ * so there's ONE source of truth — no per-project hardcoded domain. Renders
+ * nothing when R2_PUBLIC_URL isn't set (local disk / no CDN → nothing to
+ * preconnect).
+ *
+ * Server Component — drop it in the <head> of your locale layout:
+ *
+ *   import { MediaPreconnect } from '@intecion/ipal-kit/rsc'
+ *   // in <head> (or top of <body> — Next hoists link tags):
+ *   <MediaPreconnect />
+ */
+export declare function MediaPreconnect(): import("react/jsx-runtime").JSX.Element | null;
+export default MediaPreconnect;

dist/modules/storage/MediaPreconnect.js

@@ -0,0 +1,47 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * Emits <link rel="preconnect"> + <link rel="dns-prefetch"> for the media CDN
+ * domain (R2_PUBLIC_URL), so the browser opens the TLS/DNS connection to the
+ * media host early — before it hits the first <img>. Saves ~150–300ms on the
+ * first image load.
+ *
+ * Reads the domain from R2_PUBLIC_URL (the same env var buildR2Storage uses),
+ * so there's ONE source of truth — no per-project hardcoded domain. Renders
+ * nothing when R2_PUBLIC_URL isn't set (local disk / no CDN → nothing to
+ * preconnect).
+ *
+ * Server Component — drop it in the <head> of your locale layout:
+ *
+ *   import { MediaPreconnect } from '@intecion/ipal-kit/rsc'
+ *   // in <head> (or top of <body> — Next hoists link tags):
+ *   <MediaPreconnect />
+ */ export function MediaPreconnect() {
+    const publicUrl = process.env.R2_PUBLIC_URL?.replace(/\/$/, '');
+    if (!publicUrl) {
+        return null;
+    }
+    // Origin only (scheme + host) — preconnect targets an origin, not a path.
+    let origin;
+    try {
+        origin = new URL(publicUrl).origin;
+    } catch  {
+        return null // malformed URL → skip rather than emit a broken tag
+        ;
+    }
+    return /*#__PURE__*/ _jsxs(_Fragment, {
+        children: [
+            /*#__PURE__*/ _jsx("link", {
+                crossOrigin: "anonymous",
+                href: origin,
+                rel: "preconnect"
+            }),
+            /*#__PURE__*/ _jsx("link", {
+                href: origin,
+                rel: "dns-prefetch"
+            })
+        ]
+    });
+}
+export default MediaPreconnect;
+
+//# sourceMappingURL=MediaPreconnect.js.map

dist/modules/storage/MediaPreconnect.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/modules/storage/MediaPreconnect.tsx"],"sourcesContent":["/**\n * Emits <link rel=\"preconnect\"> + <link rel=\"dns-prefetch\"> for the media CDN\n * domain (R2_PUBLIC_URL), so the browser opens the TLS/DNS connection to the\n * media host early — before it hits the first <img>. Saves ~150–300ms on the\n * first image load.\n *\n * Reads the domain from R2_PUBLIC_URL (the same env var buildR2Storage uses),\n * so there's ONE source of truth — no per-project hardcoded domain. Renders\n * nothing when R2_PUBLIC_URL isn't set (local disk / no CDN → nothing to\n * preconnect).\n *\n * Server Component — drop it in the <head> of your locale layout:\n *\n *   import { MediaPreconnect } from '@intecion/ipal-kit/rsc'\n *   // in <head> (or top of <body> — Next hoists link tags):\n *   <MediaPreconnect />\n */\nexport function MediaPreconnect() {\n  const publicUrl = process.env.R2_PUBLIC_URL?.replace(/\\/$/, '')\n  if (!publicUrl) {return null}\n\n  // Origin only (scheme + host) — preconnect targets an origin, not a path.\n  let origin: string\n  try {\n    origin = new URL(publicUrl).origin\n  } catch {\n    return null // malformed URL → skip rather than emit a broken tag\n  }\n\n  return (\n    <>\n      <link crossOrigin=\"anonymous\" href={origin} rel=\"preconnect\" />\n      <link href={origin} rel=\"dns-prefetch\" />\n    </>\n  )\n}\n\nexport default MediaPreconnect\n"],"names":["MediaPreconnect","publicUrl","process","env","R2_PUBLIC_URL","replace","origin","URL","link","crossOrigin","href","rel"],"mappings":";AAAA;;;;;;;;;;;;;;;;CAgBC,GACD,OAAO,SAASA;IACd,MAAMC,YAAYC,QAAQC,GAAG,CAACC,aAAa,EAAEC,QAAQ,OAAO;IAC5D,IAAI,CAACJ,WAAW;QAAC,OAAO;IAAI;IAE5B,0EAA0E;IAC1E,IAAIK;IACJ,IAAI;QACFA,SAAS,IAAIC,IAAIN,WAAWK,MAAM;IACpC,EAAE,OAAM;QACN,OAAO,KAAK,qDAAqD;;IACnE;IAEA,qBACE;;0BACE,KAACE;gBAAKC,aAAY;gBAAYC,MAAMJ;gBAAQK,KAAI;;0BAChD,KAACH;gBAAKE,MAAMJ;gBAAQK,KAAI;;;;AAG9B;AAEA,eAAeX,gBAAe"}

docs/deployment.md

@@ -0,0 +1,206 @@
+# Deployment — zmienne środowiskowe i produkcja
+
+Jedno źródło prawdy o zmiennych środowiskowych (wszystkie, co znaczą, wymagane
+czy nie) oraz jak wdrożyć projekt na produkcję spójnie. Env jest częścią
+deploymentu — te same zmienne w dev (.env) i na produkcji (runtime hostingu).
+
+Powiązane: [getting-started.md](./getting-started.md), [storage.md](./storage.md)
+(R2), [email.md](./email.md) (Graph), [security.md](./security.md).
+
+---
+
+## 1. ZMIENNE ŚRODOWISKOWE — pełna lista
+
+### Rdzeń (WYMAGANE — projekt bez nich nie wstanie)
+
+```bash
+# Baza danych (Mongo albo Postgres — zależnie od projektu)
+DATABASE_URI=mongodb://...          # albo postgres://... / file:./dev.db (dev)
+
+# Sekret Payload (podpisywanie sesji/tokenów) — losowy, długi
+PAYLOAD_SECRET=<losowy-ciąg-min-32-znaki>
+
+# Publiczny URL serwisu (canonical, hreflang, OG, manifest)
+NEXT_PUBLIC_SERVER_URL=https://klient.pl    # dev: http://localhost:3000
+```
+
+### Email — Graph (OPCJONALNE, agencyjne, gdy transport = Graph)
+
+```bash
+GRAPH_TENANT_ID=<azure-tenant-id>
+GRAPH_CLIENT_ID=<azure-app-client-id>
+GRAPH_CLIENT_SECRET=<azure-app-secret>
+GRAPH_SENDER=noreply@mailservice.intecion.net   # wspólna skrzynka
+```
+Bez nich transport Graph nie zadziała (fallback SMTP). Patrz email.md.
+
+### Storage — R2 (OPCJONALNE, gdy media w R2)
+
+```bash
+R2_BUCKET=<nazwa-bucketa>
+R2_ENDPOINT=https://<ACCOUNT_ID>.r2.cloudflarestorage.com
+R2_ACCESS_KEY_ID=<access-key>
+R2_SECRET_ACCESS_KEY=<secret-key>
+R2_PUBLIC_URL=https://media.klient.pl    # custom domena (obrazy publiczne)
+```
+Brak → fallback na lokalny dysk. Patrz storage.md.
+
+### Tabela — wszystkie zmienne
+
+| Zmienna | Wymagana | Warstwa | Opis |
+|---|---|---|---|
+| `DATABASE_URI` | ✅ | infra | połączenie z bazą |
+| `PAYLOAD_SECRET` | ✅ | infra | sekret Payload |
+| `NEXT_PUBLIC_SERVER_URL` | ✅ | infra | publiczny URL (canonical, OG) |
+| `GRAPH_TENANT_ID` | ⬜ | email | Azure tenant (Graph) |
+| `GRAPH_CLIENT_ID` | ⬜ | email | Azure app id |
+| `GRAPH_CLIENT_SECRET` | ⬜ | email | Azure secret |
+| `GRAPH_SENDER` | ⬜ | email | skrzynka nadawcza |
+| `R2_BUCKET` | ⬜ | storage | bucket R2 |
+| `R2_ENDPOINT` | ⬜ | storage | endpoint S3 R2 |
+| `R2_ACCESS_KEY_ID` | ⬜ | storage | klucz R2 |
+| `R2_SECRET_ACCESS_KEY` | ⬜ | storage | sekret R2 |
+| `R2_PUBLIC_URL` | ⬜ | storage | custom domena mediów |
+
+**Zasada:** wszystkie sekrety to zmienne agencyjne/infrastrukturalne — w `.env`
+(dev) i runtime hostingu (prod), NIGDY w repo. Dane per-projekt edytowalne przez
+redaktora idą do PANELU, nie do env (patrz architektura-tresci.md).
+
+### .env.example — zawsze w repo
+
+Każdy projekt ma `.env.example` z listą zmiennych (bez wartości/sekretów) —
+szablon dla następnej osoby. Commituj go; `.env` (z wartościami) NIGDY.
+
+---
+
+## 2. PRZED DEPLOYEM — checklist
+
+- [ ] `pnpm build --webpack` przechodzi LOKALNIE (nie tylko dev)
+- [ ] Wszystkie wymagane env ustawione na hostingu (runtime)
+- [ ] `NEXT_PUBLIC_SERVER_URL` = produkcyjny URL (nie localhost)
+- [ ] `PAYLOAD_SECRET` inny niż w dev (produkcyjny sekret)
+- [ ] Baza produkcyjna (nie dev/SQLite)
+- [ ] HSTS włączony (buildSecurityHeaders hsts: production)
+- [ ] Media: R2 z custom domeną (jeśli używane) — obrazy publiczne
+- [ ] Migracja mediów lokalne→R2 (jeśli przełączasz)
+- [ ] Strony polityk + baner cookies (patrz wymagania-prawne.md)
+
+---
+
+## 3. BUDOWANIE NA PRODUKCJĘ
+
+### Build script (Next 16 + Payload)
+
+```json
+// package.json — --webpack KONIECZNE (Turbopack konfliktuje z withPayload)
+"build": "cross-env NODE_OPTIONS=\"--max-old-space-size=3072\" next build --webpack"
+```
+
+`--max-old-space-size` — Payload + Next bywają pamięciożerne przy buildzie;
+3072 MB zapobiega OOM na mniejszych maszynach.
+
+### Kolejność build → migracje → start
+
+```bash
+pnpm install --frozen-lockfile   # dokładnie z lockfile (powtarzalny build)
+pnpm generate:types              # typy z kolekcji
+pnpm build                       # --webpack
+# migracje bazy (jeśli Postgres z migracjami):
+pnpm payload migrate
+pnpm start                       # produkcyjny serwer
+```
+
+---
+
+## 3a. Pułapka: metadata w <body> zamiast <head> (htmlLimitedBots)
+
+Next 16 streamuje metadata dynamicznych stron do `<body>` (przenosi do head
+skryptem JS). Crawlery bez JS widzą canonical/hreflang/title/favicon poza head →
+utrata SEO. **Każdy projekt** tego potrzebuje w next.config:
+
+```ts
+const nextConfig: NextConfig = {
+  htmlLimitedBots:
+    /Googlebot|Google-InspectionTool|Bingbot|Yandex|DuckDuckBot|Screaming Frog|AhrefsBot|SemrushBot/i,
+  // ...
+}
+```
+
+Weryfikacja: `curl -A "Googlebot" URL | grep canonical` — musi być w `<head>`.
+Szczegóły i objawy: seo.md (sekcja htmlLimitedBots).
+
+## 3b. Pułapka: prerender tras zależnych od bazy (KONIECZNE)
+
+Next domyślnie **prerenderuje** trasy typu `sitemap.ts` w czasie `next build` —
+traktuje je jako statyczne. Jeśli taka trasa czyta bazę (sitemap → Payload →
+Mongo/Postgres), build **próbuje połączyć się z bazą**. A kontener budujący
+(Coolify/Docker/Railway/CI) zwykle NIE ma dostępu do sieci bazy → połączenie
+pada (`ENOTFOUND`, `MongooseServerSelectionError`) → **build się wywala**.
+
+**Rozwiązanie — `force-dynamic` na trasach zależnych od bazy:**
+```ts
+// app/sitemap.ts
+export { sitemap as default } from '@/lib/content'
+export const dynamic = 'force-dynamic'   // generuj w runtime, nie w buildzie
+```
+
+To mówi Next: nie prerenderuj w buildzie, generuj w runtime (gdy baza jest
+dostępna). Dotyczy KAŻDEJ trasy czytającej bazę podczas renderowania:
+- `app/sitemap.ts` → `force-dynamic`
+- inne trasy/strony czytające bazę w prerenderze → rozważ `force-dynamic` albo
+  obsłuż błąd bazy (try/catch z fallbackiem)
+
+Plugin dodatkowo zabezpiecza handler sitemap (łapie błąd bazy, zwraca pustą
+mapę), więc build nie padnie nawet bez `force-dynamic` — ale to siatka
+bezpieczeństwa, nie właściwe rozwiązanie. Zawsze dodawaj `force-dynamic`.
+
+**Strona 404** (`not-found.tsx`) czytająca ustawienia z bazy — ten sam problem.
+Opakuj `getCachedPayload()` w try/catch, żeby brak bazy w buildzie nie wywalił
+prerenderu 404 (fallback na statyczne teksty).
+
+**Weryfikacja lokalna** (symuluj brak bazy):
+```bash
+DATABASE_URI=mongodb://invalid-host:27017/test pnpm build
+# build musi przejść (kod 0), mimo niedostępnej bazy
+```
+
+## 4. HOSTING (Coolify / Docker)
+
+### Zmienne runtime, nie build
+
+Zmienne środowiskowe ustaw w **runtime** hostingu (Coolify → Environment
+Variables), nie zapiekaj w build. `NEXT_PUBLIC_*` są wyjątkiem — wchodzą w build
+(bo publiczne, w bundlu klienta), więc muszą być dostępne PODCZAS buildu.
+
+### Persystencja mediów
+
+Jeśli media lokalne (nie R2) — potrzebują **wolumenu** (inaczej znikną przy
+redeployu). Dlatego R2 jest zalecane na produkcji: media poza kontenerem,
+przetrwają redeploy. Patrz storage.md.
+
+### Health check
+
+Payload wystawia panel pod `/admin` — health check może pingować stronę główną
+albo `/admin`. Nie ustawiaj health check na endpoint wymagający bazy, jeśli
+baza wstaje wolniej niż app.
+
+---
+
+## 5. PO DEPLOYU — weryfikacja
+
+- [ ] Strona główna `/` przekierowuje na locale (`/pl`)
+- [ ] Panel `/admin` działa, logowanie OK
+- [ ] Formularz wysyła (test przez panel: Send test)
+- [ ] Media się wyświetlają (jeśli R2 — custom domena działa, nie 403)
+- [ ] Favicon w `<head>` (patrz seo.md — Google cache'uje wolno)
+- [ ] HTTPS + nagłówki bezpieczeństwa (sprawdź np. securityheaders.com)
+- [ ] Sitemap `/sitemap.xml` i `/robots.txt` odpowiadają
+
+---
+
+## DLACZEGO TO WAŻNE
+
+- **Jedna lista env** — nikt nie zgaduje, czego brakuje
+- **Powtarzalny deploy** — frozen-lockfile, ta sama kolejność, każdy projekt tak samo
+- **Sekrety bezpieczne** — env/runtime, nigdy repo
+- **Media przetrwają** — R2 albo wolumen, nie znikają przy redeployu

docs/i18n.md

@@ -55,6 +55,21 @@ buildLocalizedPath({ slugs, locale: 'en', config })   // '/en/about'
 buildLocalizedPath({ slugs: { en: 'home' }, locale: 'en', config })  // '/en'
 ```
 
+> **Pułapka typu (TypeScript):** przy `locale: 'all'` Payload w RUNTIME zwraca
+> zlokalizowane pole jako obiekt `{ pl, en }`, ale wygenerowane typy Payloada
+> deklarują `doc.slug` jako `string` (typ nie odróżnia trybu `all`). `tsc`
+> zgłosi więc niezgodność. Rozwiązanie — czyste rzutowanie na oczekiwany przez
+> helper typ:
+> ```ts
+> const slugs = getLocalizedSlugs({
+>   slugField: doc.slug as unknown as Record<string, unknown>,
+>   config,
+> })
+> ```
+> To nie hack — to pomost między statycznym typem (string) a rzeczywistym
+> kształtem runtime (obiekt), którego generator typów Payloada nie modeluje.
+> `as unknown as` jest tu poprawne, bo TS nie zna trybu `all`.
+
 ### Przełącznik języka (bez 404)
 
 ```ts

docs/security.md

@@ -62,3 +62,80 @@ ZAWSZE wyłączaj w dev: `hsts: process.env.NODE_ENV === 'production'`.
 `additional` z tym samym kluczem NADPISUJE domyślny (np. zmień X-Frame-Options
 na SAMEORIGIN). Nowy klucz (jak CSP) dodaje. CSP zawsze przez `additional` —
 plugin go nie generuje, bo zależy od projektu.
+
+### Dlaczego CSP zostaje w projekcie (nie plugin)
+
+HSTS, nosniff, Referrer-Policy są IDENTYCZNE dla każdego projektu → plugin je
+generuje. CSP wylicza KONKRETNE domeny, z których projekt ładuje (jego R2,
+analytics, Turnstile, fonty). Generyczny CSP byłby albo za luźny (`*` =
+bezużyteczny), albo psułby stronę. Więc plugin daje mechanizm (`additional`),
+projekt dostarcza CSP dopasowany do siebie.
+
+### Budowa CSP — domeny z env, nie hardkod
+
+Domenę mediów czytaj z `R2_PUBLIC_URL` (env), nie zaszywaj. Resztę źródeł
+dopasuj do tego, co projekt faktycznie ładuje:
+
+```ts
+// next.config.ts
+const r2Url = process.env.R2_PUBLIC_URL || ''
+
+const csp = [
+  "default-src 'self'",
+  // skrypty: self + Turnstile (Cloudflare) + analytics (GTM/GA jeśli używasz)
+  "script-src 'self' 'unsafe-inline' https://challenges.cloudflare.com https://www.googletagmanager.com",
+  // style: self + inline (Tailwind) + Google Fonts
+  "style-src 'self' 'unsafe-inline' https://fonts.googleapis.com",
+  // obrazy: self + media R2 (z env!) + data:
+  `img-src 'self' data: ${r2Url}`.trim(),
+  "font-src 'self' https://fonts.gstatic.com data:",
+  "connect-src 'self' https://www.google-analytics.com",
+  // ramki: Turnstile (widget captcha)
+  "frame-src https://challenges.cloudflare.com",
+  "form-action 'self'",
+  "frame-ancestors 'none'",   // zastępuje X-Frame-Options w nowych przeglądarkach
+].join('; ')
+
+const securityHeaders = buildSecurityHeaders({
+  hsts: process.env.NODE_ENV === 'production',
+  additional: [{ key: 'Content-Security-Policy', value: csp }],
+})
+```
+
+Dopasuj źródła do projektu: mapy Google (`https://maps.googleapis.com`,
+`https://*.google.com`), inne embedy, inne analytics. To, czego nie wymienisz,
+zostanie zablokowane.
+
+### WDRAŻAJ CSP OSTROŻNIE — najpierw Report-Only
+
+CSP za ścisły **psuje stronę** (blokuje skrypty/style/obrazy). NIGDY nie wdrażaj
+enforcing CSP na ślepo. Metoda bezpieczna:
+
+1. **Najpierw raportowanie** — użyj klucza `Content-Security-Policy-Report-Only`
+   (nie `Content-Security-Policy`). Przeglądarka RAPORTUJE naruszenia w konsoli,
+   ale NIE blokuje — strona działa normalnie.
+   ```ts
+   additional: [{ key: 'Content-Security-Policy-Report-Only', value: csp }]
+   ```
+2. **Otwórz stronę** → DevTools → Console → szukaj „Content Security Policy"
+   violations. Każde naruszenie = brakująca domena. Dodaj ją do odpowiedniej
+   dyrektywy CSP.
+3. **Przejdź przez cały serwis** — strona główna, formularze (Turnstile!),
+   galeria (obrazy R2), strony z mapą/embedami. Zbierz wszystkie naruszenia.
+4. **Dopiero gdy konsola czysta** → zmień klucz na `Content-Security-Policy`
+   (enforcing). Teraz CSP chroni, nie psując.
+
+### Weryfikacja nagłówków na produkcji
+
+```bash
+# sprawdź, które nagłówki faktycznie wychodzą:
+curl -sI https://<DOMENA>/pl | grep -i "strict-transport\|content-type-options\|referrer\|content-security\|x-frame"
+```
+
+Jeśli HSTS/nosniff/Referrer są, a CSP brak → dodaj CSP (wyżej). Jeśli BRAK
+wszystkich mimo buildSecurityHeaders w config → sprawdź, czy `headers()` jest
+wpięte i czy Cloudflare (jeśli przed aplikacją) nie filtruje nagłówków.
+
+> Uwaga Cloudflare: jeśli CF jest przed aplikacją, może nadpisywać/filtrować
+> nagłówki. Wtedy ustaw je też w CF (Transform Rules → Modify Response Header)
+> albo upewnij się, że CF przepuszcza nagłówki z origin.

docs/seo.md

@@ -217,6 +217,7 @@ export const { /* ... */, sitemap, robots } = createContentHelpers({
 ```ts
 // app/sitemap.ts
 export { sitemap as default } from '@/lib/content'
+export const dynamic = 'force-dynamic' // generuj w runtime, nie w buildzie
 
 // app/robots.ts
 export { robots as default } from '@/lib/content'
@@ -227,6 +228,16 @@ całkiem w pluginie — Next tworzy te trasy wyłącznie z plików w `app/`, ska
 katalog projektu, nie node_modules. Ale re-eksport to maksimum redukcji: cała
 logika jest w pluginie.
 
+> **Deploy kontenerowy (Coolify/Docker/Railway/CI) — WAŻNE:** `export const
+> dynamic = 'force-dynamic'` w `app/sitemap.ts` jest KONIECZNE. Bez niego Next
+> traktuje sitemap jako statyczny i prerenderuje go w `next build` — a to
+> wywołuje Payload → bazę. Kontener budujący zwykle nie ma dostępu do sieci
+> Docker, więc połączenie z bazą pada (`ENOTFOUND`) i build się wywala. Z
+> `force-dynamic` sitemap generuje się w runtime, gdy baza jest dostępna.
+> (Plugin dodatkowo łapie błąd bazy i zwraca pusty sitemap zamiast wywalić build
+> — ale `force-dynamic` to właściwe rozwiązanie, nie poleganie na fallbacku.)
+> Opcjonalnie `export const revalidate = 3600` — cache sitemap na godzinę.
+
 Co zawiera sitemapa:
 - każdą stronę i wpis bloga, URL w domyślnym locale
 - `alternates.languages` → Next renderuje `<xhtml:link rel="alternate" hreflang>`
@@ -248,3 +259,455 @@ const entries = await buildSitemapEntries({
 
 Przy dziesiątkach tysięcy URL-i Next ma `generateSitemaps` do dzielenia na
 części — dodasz, gdyby realnie było ich tyle. Jedna sitemapa wystarcza do ~50k.
+
+## Favicon w Google + Organization (branding w wyszukiwarce)
+
+Favicon i structured data wpływają na to, jak strona wygląda w wynikach Google.
+Plugin generuje jedno i drugie z panelu — projekt tylko wpina w root layout.
+
+### Favicon — format: PNG, nie SVG (ważne)
+
+**Dla Google użyj PNG (≥48×48), nie SVG.** Zweryfikowane: Google niezawodnie
+wspiera PNG i ICO, ale **SVG w wynikach Google jest zawodny** — często pokazuje
+glob mimo że w karcie przeglądarki favicon renderuje się dobrze. Oficjalna
+dokumentacja Google nie wymienia SVG. Jeśli zależy Ci na faviconie w wyszukiwarce
+— wgraj PNG.
+
+- **PNG ≥48×48** (idealnie 96 lub 192), kwadratowy → działa w Google ✓
+- **SVG** → działa w przeglądarce, ale w Google glob (zawodne) ✗
+- Walidacja pola favicon OSTRZEGA, gdy wgrasz SVG (żebyś wiedział, że dla search
+  potrzebny PNG).
+
+### Favicon — dlaczego się nie pokazywał
+
+Google ma twarde wymogi: `<link rel="icon">` w `<head>`, kwadratowy, **≥48×48px**,
+stały URL. Gdy projekt renderował favicon „po swojemu", często był za mały, źle
+otagowany albo nieobecny w head → Google go nie pokazywał. Plugin robi to teraz
+poprawnie.
+
+### Wpięcie favicon (root layout)
+
+Favicon jest GLOBALNY (ten sam wszędzie) — wpina się RAZ w root layout, nie per strona:
+
+```tsx
+// app/(frontend)/[locale]/layout.tsx
+import type { Metadata } from 'next'
+import { buildIconsMetadata } from '@intecion/ipal-kit'
+import { getSettings } from '@/lib/payload'
+
+export async function generateMetadata({ params }): Promise<Metadata> {
+  const { locale } = await params
+  const settings = await getSettings(locale)
+  return buildIconsMetadata(settings.favicon)   // z pola favicon (panel)
+}
+```
+
+`buildIconsMetadata` generuje poprawne `icons` (favicon + apple-touch) z pola
+favicon. SVG → skaluje się; PNG → powinien być ≥48×48 (walidacja ostrzega, patrz niżej).
+
+### Wymuszenie rozmiaru (walidacja)
+
+Pole favicon w SiteSettings ma walidację `validateFaviconField` — ostrzega
+redaktora przy zapisie, jeśli favicon jest <48×48 albo nie kwadratowy. Redaktor
+widzi ostrzeżenie, zamiast po cichu wgrać favicon, którego Google nie pokaże.
+
+### Organization JSON-LD (branding)
+
+Pomaga Google powiązać stronę z marką (nazwa, logo) — lepsze wyświetlanie w
+wynikach, logo w knowledge panel.
+
+```tsx
+// root layout — RAZ (Organization jest globalny)
+import { buildOrganizationJsonLd } from '@intecion/ipal-kit'
+
+const jsonLd = buildOrganizationJsonLd({
+  name: settings.siteName,
+  url: process.env.NEXT_PUBLIC_SERVER_URL!,
+  logo: settings.logo,
+  sameAs: settings.socialLinks,   // opcjonalne: profile społecznościowe
+})
+
+// w JSX layoutu:
+<script
+  type="application/ld+json"
+  dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
+/>
+```
+
+Dane z panelu (siteName, logo) — nic na sztywno.
+
+### Po wdrożeniu — cierpliwość z Google
+
+Google **cache'uje favicon osobno i wolno** (dni, czasem tygodnie). Po poprawnym
+wpięciu favicon nie pojawi się natychmiast — Googlebot musi ponownie odwiedzić
+stronę główną. Przyspieszenie: Search Console → prośba o ponowne indeksowanie
+strony głównej. Sprawdź też, czy `/` nie blokuje Googlebota (robots) i czy
+favicon URL jest publiczny (nie za auth).
+
+### Weryfikacja
+
+1. Otwórz stronę → DevTools → Elements → `<head>` → sprawdź `<link rel="icon">`
+   z poprawnym URL.
+2. Otwórz sam URL favicon w przeglądarce — obraz się pokazuje, ≥48×48.
+3. Rich Results Test (Google) — wklej URL strony, sprawdź Organization.
+4. Search Console → poproś o ponowne indeksowanie strony głównej.
+
+## Ręczne rozszerzenia SEO/PWA (manifest itp.) — z panelu, NIE hardkod
+
+Niektóre rzeczy SEO/PWA są na tyle projekt-specyficzne i jednorazowe, że plugin
+ich nie dostarcza (byłoby przeinżynierowaniem). Robisz je w projekcie — ALE
+poprawnie: czytając z panelu/env, nie zaszywając wartości klienta.
+
+> **Zasada:** nawet gdy coś robisz ręcznie w projekcie, dane (nazwa, kolory,
+> opis, logo) czytaj z panelu (SiteSettings) albo env. Zaszyta nazwa/kolor
+> klienta = antywzorzec (patrz standardy-kodu.md). Manifest „R Custom Cars" z
+> hardkodem zadziała tylko dla jednego klienta.
+
+### Web App Manifest (PWA) — jak zrobić DOBRZE
+
+Zasada nadrzędna: **brak danych → POMIŃ pole, NIE zaszywaj wartości.** Manifest
+jest ważny bez `name`? Nie — ale lepszy manifest bez nazwy niż z cudzą nazwą
+klienta w fallbacku. Fallback z nazwą/kolorem klienta to ukryty hardkod.
+
+```ts
+// app/manifest.ts
+import type { MetadataRoute } from 'next'
+import { getCachedPayload } from '@/lib/content'
+import { getSiteSettings } from '@intecion/ipal-kit'
+import { i18nConfig } from '@/i18n.config'
+import type { SiteSetting } from '@/payload-types'
+
+export default async function manifest(): Promise<MetadataRoute.Manifest> {
+  const payload = await getCachedPayload()
+  const settings = await getSiteSettings<SiteSetting>(payload, {
+    locale: i18nConfig.defaultLocale as never,
+  })
+
+  const siteName = settings?.siteName?.trim()
+
+  // Ikona z panelu (favicon → logo). Dla PNG podaj KONKRETNY rozmiar z media
+  // (nie 'any' — 'any' jest tylko dla SVG). Bez ikony → pomiń pole icons.
+  const icon = settings?.favicon ?? settings?.logo
+  const iconEntry =
+    typeof icon === 'object' && icon?.url
+      ? (() => {
+          const isSvg = icon.mimeType === 'image/svg+xml' || icon.url.endsWith('.svg')
+          const size =
+            typeof icon.width === 'number' && typeof icon.height === 'number'
+              ? `${Math.min(icon.width, icon.height)}x${Math.min(icon.width, icon.height)}`
+              : '512x512'
+          return {
+            src: icon.url,
+            type: icon.mimeType ?? 'image/png',
+            sizes: isSvg ? 'any' : size, // 'any' tylko dla SVG
+          }
+        })()
+      : undefined
+
+  // Buduj TYLKO z tego, co jest. Brak pola → nie ma go w manifeście (zamiast
+  // zaszytego fallbacku). start_url z configu, nie zaszyte '/pl'.
+  return {
+    ...(siteName ? { name: siteName, short_name: siteName } : {}),
+    start_url: `/${i18nConfig.defaultLocale}`,
+    display: 'standalone',
+    ...(iconEntry ? { icons: [iconEntry] } : {}),
+    // theme_color / background_color / description — TYLKO jeśli dodasz pola w
+    // panelu i je odczytasz. NIE zaszywaj '#0e1e24' ani opisu klienta.
+  }
+}
+```
+
+**Kluczowe różnice od częstego błędu agenta:**
+- **Brak fallbacku z nazwą klienta** — `siteName` puste → pomijamy `name`, nie
+  wstawiamy „Kancelaria X" na sztywno. Cudza nazwa w fallbacku = hardkod.
+- **PNG dostaje konkretny `sizes`** z wymiarów media (nie `sizes: 'any'` — to
+  ten sam błąd co przy favicon; `any` tylko dla SVG).
+- **Brak bloku `catch` z hardkodami** — jeśli boisz się błędu, opakuj samo
+  `getSiteSettings` i przy błędzie zwróć minimalny manifest (start_url + display),
+  BEZ zaszytej nazwy/kolorów.
+- **start_url z i18nConfig**, nie zaszyte `/pl`.
+
+**Kontrast — czego NIE robić** (realne błędy z projektów):
+
+```ts
+// ŹLE — hardkod jawny (rcustomcars)
+let name = 'R Custom Cars'; short_name: 'RCC'
+background_color: '#08080a', theme_color: '#d4af37'
+icons: [{ src: '/logo/rcc-logo.svg' }]              // statyczna ścieżka
+
+// ŹLE — hardkod UKRYTY w fallbacku (kancelaria)
+siteName || 'Kancelaria Adwokacka Adwokat Romuald Kędzierski'   // cudza nazwa w ||
+sizes: 'any', type: mimeType                        // 'any' na PNG = źle
+catch { return { name: 'Kancelaria...', theme_color: '#0e1e24' } }  // hardkod w catch
+```
+
+Fallback `|| 'Nazwa Klienta'` wygląda niewinnie, ale to hardkod — inny projekt
+skopiuje i pokaże cudzą nazwę, gdy panel zawiedzie. Brak danych → pomiń pole.
+
+Jeśli klient potrzebuje kolorów motywu / opisu w manifeście — **dodaj pola**
+`themeColor`, `manifestDescription` w SiteSettings (przez opcje pluginu
+SiteSettingsFields) i czytaj z panelu. Wtedy redaktor je zmienia, nie są zaszyte.
+
+### Inne ręczne rozszerzenia — ta sama zasada
+
+Cokolwiek dodajesz ręcznie (dodatkowe meta tagi, structured data konkretnego
+typu, itp.):
+- dane z panelu (SiteSettings / pola strony) albo env
+- nic zaszytego per klient (nazwa, kolor, adres, domena)
+- jeśli to uniwersalne i powtarzalne → rozważ zgłoszenie do pluginu zamiast
+  ręcznie (patrz ANTIGRAVITY-ZASADY-AGENT.md A0)
+
+## KRYTYCZNE: metadata w <head> dla Google (htmlLimitedBots)
+
+**Największa pułapka SEO w Next.js — dotyczy KAŻDEGO projektu.** Dla dynamicznie
+renderowanych stron (SSR) Next.js **streamuje metadata do `<body>`**, nie `<head>`,
+i przenosi ją do head skryptem JS. Skutek: canonical, hreflang, title, favicon
+lądują w body w surowym HTML. Crawlery, które nie wykonują JS (Screaming Frog,
+część botów), widzą je poza head → ignorują → utrata SEO.
+
+Google *twierdzi*, że wykonuje JS i widzi przeniesione tagi, ale praktyka
+(i audyty) pokazują realne problemy z indeksacją canonical. Bezpieczniej wymusić
+metadata do head dla crawlerów.
+
+### Rozwiązanie — htmlLimitedBots w next.config
+
+```ts
+// next.config.ts
+const nextConfig: NextConfig = {
+  // Wymusza blocking metadata (canonical, hreflang, title, favicon) w <head>
+  // dla crawlerów SEO — zamiast streamingu do <body>.
+  htmlLimitedBots:
+    /Googlebot|Google-InspectionTool|Storebot-Google|Bingbot|Yandex|DuckDuckBot|Baiduspider|Screaming Frog|AhrefsBot|SemrushBot/i,
+  // ...reszta
+}
+```
+
+`htmlLimitedBots` mówi Next: dla tych User-Agentów wyłącz streaming, wstaw
+metadata do `<head>` w surowym HTML (blocking). Użytkownicy dalej dostają
+streaming (szybkie ładowanie); crawlery dostają poprawny head.
+
+### Objawy (że masz ten problem)
+
+- Screaming Frog: „canonical/hreflang/title outside <head>"
+- Search Console: „brak canonical", favicon nie pokazuje się (glob)
+- W surowym HTML canonical/title są PO `</head>`, na końcu body, ze skryptem
+  `document.querySelectorAll('body link[rel=icon]')...appendChild`
+
+### Weryfikacja
+
+```bash
+# jako Googlebot — metadata MUSI być w <head>
+curl -A "Googlebot" https://twojadomena.pl/pl/strona | grep -o '<head>.*</head>' | grep canonical
+# jako user — streaming (metadata w body — OK dla ludzi wykonujących JS)
+curl -A "Mozilla/5.0" https://twojadomena.pl/pl/strona
+```
+
+Bez htmlLimitedBots ten sam problem dotknie favicon (glob w Google), canonical
+(„User-declared canonical: None"), hreflang i title. Jedna linia w config
+naprawia wszystko naraz.
+
+## SEO wielojęzyczne — hreflang, x-default, redirect roota
+
+Przekierowanie `/` → `/pl` (negocjacja locale) może wpływać na SEO. Kluczowe:
+plugin generuje hreflang, więc Google rozumie, że `/pl` i `/en` to wersje
+językowe (nie duplikaty). Ale są niuanse.
+
+### hreflang + x-default (generowane przez plugin)
+
+`buildHreflangAlternates` generuje `alternates.languages` z wpisami per locale
+ORAZ **`x-default`** wskazujący na defaultLocale. x-default mówi Google: „gdy
+język/region użytkownika nie pasuje do żadnej wersji, użyj TEJ" — co pokrywa
+sytuację roota (Googlebot bez preferencji językowej). Bez x-default Google
+zgadywałby; z nim dostaje jasną wskazówkę (domyślnie pl).
+
+Działa automatycznie przez createPageMetadata (canonical + hreflang + x-default).
+
+### Redirect roota — na co uważać
+
+- **307 (temporary)** na `/` → `/pl` — plugin tak robi. Dla warunkowego redirectu
+  (zależnego od negocjacji) to obronne. Google i tak podąża.
+- **Negocjacja Accept-Language** — Googlebot bywa z `Accept-Language: en` albo
+  bez. Może trafić na `/en`. x-default (→ pl) łagodzi to: Google wie, że
+  domyślna wersja to polska.
+- **Root nie ma własnej treści** — cała moc idzie przez redirect na locale. To
+  normalne dla i18n stron, hreflang to obsługuje.
+
+### Weryfikacja SEO wielojęzycznego
+
+1. Search Console → Inspekcja URL dla `/` — zobacz, na co Google przekierowuje
+   i co indeksuje.
+2. Sprawdź, czy `/pl` i `/en` są indeksowane osobno (nie jako duplikaty).
+3. Rich Results / źródło strony → potwierdź `<link rel="alternate" hreflang="...">`
+   z wpisami per locale + `hreflang="x-default"`.
+4. Search Console → raport Międzynarodowe targetowanie (jeśli dostępny) — błędy
+   hreflang.
+
+### Częste błędy (nie rób tak)
+
+- Brak hreflang → Google traktuje wersje jako duplikaty (plugin to ma, nie usuwaj).
+- Zaszyta mapa ścieżek zamiast getLocalizedSlugs → hreflang się rozjedzie z bazą.
+- `noindex` na `/pl` przez pomyłkę → wypada z indeksu. Sprawdź robots meta.
+- Redirect roota na twardo 301 do jednego języka → tracisz negocjację i drugą
+  wersję. Zostaw negocjację + hreflang.
+
+## Sitelinks i structured data (branding w wynikach Google)
+
+Cel: żeby wyszukanie marki („rcustomcars") pokazało stronę główną + podlinki
+(sitelinks) z opisami. Ważne — **sitelinków NIE DA SIĘ wymusić.** Google
+generuje je algorytmicznie ze struktury strony, linkowania wewnętrznego, jasnych
+tytułów i rankingu. Żaden kod ich nie włączy. Plugin dostarcza SYGNAŁY, które
+zwiększają szansę — nie gwarancję.
+
+### Co realnie wpływa na sitelinki (kolejność wg wagi)
+
+1. **Ranking na 1. stronie Google** — bez tego sitelinków nie ma. To robota SEO
+   (treść, linki), nie kodu.
+2. **Czysta struktura + jasne tytuły** — logiczna hierarchia stron, opisowe title
+   (nie „Strona 1"). Patrz fundamenty-projektu.md.
+3. **Linkowanie wewnętrzne** — ważne strony podlinkowane z głównej.
+4. **Structured data** (poniżej) — sygnał pomocniczy, nie przełącznik.
+5. **Sitemap + robots** — żeby Google w ogóle widział wszystkie strony (patrz
+   niżej — to fundament, sprawdź czy działa!).
+
+### Structured data z pluginu — 3 helpery
+
+Wszystkie emitowane jako `<script type="application/ld+json">`, dane z panelu.
+
+**1. WebSite + SearchAction (największy realny efekt)** — może dać sitelinks
+searchbox (pole wyszukiwania pod wynikiem marki). RAZ w root layout:
+```tsx
+import { buildWebSiteJsonLd } from '@intecion/ipal-kit'
+const jsonLd = buildWebSiteJsonLd({
+  name: settings.siteName,
+  url: baseUrl,
+  // TYLKO jeśli masz działającą stronę wyszukiwania:
+  search: { target: `${baseUrl}/szukaj?q={search_term_string}` },
+})
+```
+Pomiń `search`, jeśli nie ma realnej wyszukiwarki — SearchAction wskazujący na
+nieistniejącą stronę szkodzi.
+
+**2. BreadcrumbList (realny efekt)** — okruszki w wynikach (Dom › Usługi ›
+Detailing) + Google rozumie hierarchię. PER STRONA, z pozycji strony:
+```tsx
+import { buildBreadcrumbJsonLd } from '@intecion/ipal-kit'
+const jsonLd = buildBreadcrumbJsonLd([
+  { name: 'Strona główna', url: `${base}/pl` },
+  { name: 'Usługi', url: `${base}/pl/uslugi` },
+  { name: 'Detailing', url: `${base}/pl/uslugi/detailing` },
+])
+```
+Okruszki buduj z RZECZYWISTEJ pozycji strony (resolveRoute / ścieżka URL), NIE z
+zaszytej listy.
+
+**3. SiteNavigationElement (słabszy, tani)** — nawigacja jako dane. RAZ, z tych
+samych pozycji co menu w headerze:
+```tsx
+import { buildSiteNavigationJsonLd } from '@intecion/ipal-kit'
+const jsonLd = buildSiteNavigationJsonLd(
+  navItems.map(i => ({ name: i.label, url: `${base}${i.href}` }))
+)
+```
+Dane z tego samego źródła co widoczne menu — nie osobna zaszyta lista.
+
+### Realne oczekiwania (ważne)
+
+- Structured data **nie gwarantuje** sitelinków — to sygnał wśród wielu.
+- Efekt (jeśli będzie) pojawia się **po tygodniach**, gdy Google przecrawluje i
+  strona rankuje.
+- Największy wpływ ma **ranking + struktura + linkowanie**, nie schema. Schema
+  pomaga Google zrozumieć, ale nie zastąpi bycia na 1. stronie.
+- Weryfikuj: Google Rich Results Test (czy schema poprawna) + Search Console
+  (co Google pokazuje dla marki).
+
+### To, co ZALEŻY OD PROJEKTU (obowiązki wpięcia)
+
+Plugin dostarcza helpery — projekt MUSI je wpiąć i podać dane z panelu:
+
+- [ ] `buildWebSiteJsonLd` w root layout (search tylko jeśli jest wyszukiwarka)
+- [ ] `buildOrganizationJsonLd` w root layout (logo, nazwa)
+- [ ] `buildBreadcrumbJsonLd` na podstronach (z realnej ścieżki)
+- [ ] `buildSiteNavigationJsonLd` z pozycji menu (jeśli jest header nav)
+- [ ] `app/robots.ts` i `app/sitemap.ts` wystawione (patrz niżej — bez tego
+  Google nie widzi stron!)
+- [ ] Jasne, opisowe tytuły stron (nie generyczne)
+- [ ] Logiczna hierarchia + linkowanie wewnętrzne z głównej
+
+Dane WSZĘDZIE z panelu (siteName, nav, logo), nigdy zaszyte.
+
+## noindex per strona (strony prawne, cienkie, wyniki wyszukiwania)
+
+Niektóre strony NIE powinny być w indeksie Google: polityki/regulamin (kanibalizują
+frazy), strony z parametrami, wyniki wyszukiwania. Plugin wspiera to przez pole
+`noindex` w meta SEO.
+
+```ts
+// w danych strony (meta): noindex: true
+// buildMetadata automatycznie doda robots: { index: false, follow: true }
+```
+
+`noindex, follow` — strona wypada z indeksu, ale linki dalej przekazują moc
+(follow). Ustaw dla:
+- polityka prywatności, regulamin, polityka cookies
+- strony z parametrami kalkulatorów, filtrów
+- wyniki wewnętrznej wyszukiwarki
+
+Redaktor zaznacza `noindex` w panelu (pole SEO strony), plugin generuje tag.
+Alternatywnie: dodaj `noindex` do System Pages o rolach prawnych automatycznie.
+
+## robots.txt — blokada parametrów (crawl budget)
+
+URL-e z parametrami (`?meter=101-120m2`, `?s=fraza`) marnują budżet indeksowania —
+Google skanuje dziesiątki pustych wariantów. Zablokuj je w robots:
+
+```ts
+// app/robots.ts
+import { buildRobots } from '@intecion/ipal-kit'
+export default function robots() {
+  return buildRobots({
+    baseUrl: process.env.NEXT_PUBLIC_SERVER_URL!,
+    disallow: ['/admin', '/api', '/*?meter=*', '/*?s=*'],  // + parametry
+  })
+}
+```
+
+Wzorce `/*?param=*` odcinają parametryzowane URL-e. Realne z audytu: 55
+niezindeksowanych stron kalkulatora — blokada w robots by temu zapobiegła.
+
+## Local SEO — LocalBusiness, Service, FAQPage (structured data)
+
+Dla firm lokalnych (usługi + miasto) — trzy schematy zwiększające widoczność
+w wynikach lokalnych i rich results.
+
+**LocalBusiness (map pack, wyniki lokalne)** — RAZ w root layout, z globala company:
+```ts
+import { buildLocalBusinessJsonLd } from '@intecion/ipal-kit'
+const jsonLd = buildLocalBusinessJsonLd({
+  name: company.name, url: baseUrl, telephone: company.phone,
+  address: company.address, openingHours: company.hours,
+  geo: company.geo, priceRange: '$$',
+})
+```
+Najważniejsze dla „usługa + miasto". Dla konkretnego typu (Dentist, Plumber)
+nadpisz `@type`.
+
+**Service (co strona oferuje)** — per strona usługowa:
+```ts
+import { buildServiceJsonLd } from '@intecion/ipal-kit'
+const jsonLd = buildServiceJsonLd({
+  name: 'Sprzątanie biur', providerName: company.name,
+  url: pageUrl, areaServed: 'Wrocław',
+})
+```
+
+**FAQPage (rich results FAQ)** — per strona z FAQ, z bloku FAQ w panelu:
+```ts
+import { buildFaqJsonLd } from '@intecion/ipal-kit'
+const jsonLd = buildFaqJsonLd(
+  faqBlock.items.map(i => ({ question: i.question, answer: i.answer }))
+)
+```
+WAŻNE: Q&A musi odpowiadać widocznej treści strony (Google flaguje rozbieżność).
+Nie wymyślaj pytań, których nie ma na stronie.
+
+Wszystkie: dane z panelu (company, bloki), jako `<script type="application/ld+json">`.

docs/storage.md

@@ -184,3 +184,28 @@ czysta nazwa trafia i do bazy, i do bucketa). Dlaczego to ważne:
 
 Sama funkcja `normalizeFilename(name)` też jest wyeksportowana, gdybyś potrzebował
 jej poza hookiem.
+
+## Preconnect do domeny mediów (wydajność)
+
+Komponent `MediaPreconnect` generuje `<link rel="preconnect">` + `dns-prefetch`
+dla domeny mediów (R2_PUBLIC_URL) — przeglądarka nawiązuje połączenie TLS/DNS
+z CDN zawczasu, zanim napotka pierwszy `<img>`. Zysk ~150–300 ms na pierwszym
+obrazie.
+
+```tsx
+// layout.tsx — w <head> (albo górze <body>, Next hoistuje link tagi)
+import { MediaPreconnect } from '@intecion/ipal-kit/rsc'
+
+<head>
+  <MediaPreconnect />
+</head>
+```
+
+Czyta domenę z **R2_PUBLIC_URL** (to samo źródło co buildR2Storage) — zero
+hardkodu, jedno źródło prawdy. Gdy R2_PUBLIC_URL nie ustawione (lokalny dysk,
+brak CDN) → nie renderuje nic. Zmiana domeny mediów = zmiana jednej zmiennej
+env, komponent podąża automatycznie.
+
+> NIE hardkoduj `<link rel="preconnect" href="https://media.klient.pl">` ręcznie
+> w layoutcie — to zaszywa domenę klienta w kodzie. Użyj MediaPreconnect, który
+> bierze ją z env.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intecion/ipal-kit",
-  "version": "1.0.22",
+  "version": "1.2.2",
   "description": "Intecion Payload Advanced Library — a Payload CMS 3 plugin: i18n, SEO, forms, consent, analytics, blog/archives.",
   "license": "MIT",
   "repository": {

src/exports/rsc.ts

@@ -12,3 +12,4 @@ export type {
   EnhanceProps,
   RenderBlocksProps,
 } from '../modules/blocks/index.js'
+export { MediaPreconnect } from '../modules/storage/MediaPreconnect.js'

src/globals/SiteSettings/fields/general.ts

@@ -1,8 +1,10 @@
 import type { Field } from 'payload'
 
+import { validateFaviconField } from '../../../modules/seo/index.js'
+
 /**
  * General site identity fields.
- * Consumed by SEO/OG (siteName, defaultShareImage) and frontend (logo).
+ * Consumed by SEO/OG (siteName, defaultShareImage) and frontend (logo, favicon).
  */
 export const generalFields: Field[] = [
   {
@@ -45,7 +47,8 @@ export const generalFields: Field[] = [
     name: 'logo',
     type: 'upload',
     admin: {
-      description: 'Primary site logo.',
+      description:
+        'Primary site logo. Also used for Organization structured data (buildOrganizationJsonLd).',
     },
     relationTo: 'media',
   },
@@ -61,7 +64,13 @@ export const generalFields: Field[] = [
     name: 'favicon',
     type: 'upload',
     admin: {
-      description: 'Square source icon (PNG or SVG) for the browser tab. Rendered by the frontend.',
+      description:
+        'Square icon, PNG or SVG, min. 48×48px (Google requires this to show it in search). Rendered via buildIconsMetadata.',
+    },
+    hooks: {
+      // Warns the editor at save time if the favicon is too small (<48×48) or
+      // not square — Google won't display such favicons in search results.
+      beforeValidate: [validateFaviconField],
     },
     relationTo: 'media',
   },

src/index.ts

@@ -99,6 +99,21 @@ export {
 } from './modules/payload/index.js'
 export { buildSecurityHeaders } from './modules/security/index.js'
 export type { BuildSecurityHeadersArgs, SecurityHeader } from './modules/security/index.js'
+export {
+  buildFaqJsonLd,
+  buildIconsMetadata,
+  buildLocalBusinessJsonLd,
+  buildOrganizationJsonLd,
+  buildServiceJsonLd,
+  validateFaviconField,
+} from './modules/seo/index.js'
+// Structured data (schema.org JSON-LD) — brand/sitelink signals for Google.
+// WebSite (+ optional SearchAction), BreadcrumbList (per page), SiteNavigation.
+export {
+  buildBreadcrumbJsonLd,
+  buildSiteNavigationJsonLd,
+  buildWebSiteJsonLd,
+} from './modules/seo/index.js'
 export type { PageMetadata, SeoMeta, SeoOption } from './modules/seo/index.js'
 export { buildHreflangAlternates, buildMetadata, composeTitle } from './modules/seo/index.js'
 export type { AutoFillMapping, RobotsRules, SitemapEntry } from './modules/seo/index.js'

src/modules/frontend/createContentHelpers.ts

@@ -1,22 +1,14 @@
-import type { BasePayload, SanitizedConfig } from 'payload'
-
-import { getPayload } from 'payload'
 import { cache } from 'react'
+import type { BasePayload, SanitizedConfig } from 'payload'
+import { getPayload } from 'payload'
 
-import type { ArchiveEntries, ContentOption, ResolvedRoute } from '../content/index.js'
+import type { ContentOption, ResolvedRoute, ArchiveEntries } from '../content/index.js'
+import { resolveRoute as resolveRouteRaw, getArchiveEntries } from '../content/index.js'
 import type { I18nConfig } from '../i18n/index.js'
-import type { RobotsRules, SitemapEntry } from '../seo/index.js'
+import type { SitemapEntry, RobotsRules } from '../seo/index.js'
-
+import { buildSitemapEntries, buildRobots } from '../seo/index.js'
-import { getArchiveEntries, resolveRoute as resolveRouteRaw } from '../content/index.js'
-import { buildRobots, buildSitemapEntries } from '../seo/index.js'
 
 type CreateContentHelpersArgs = {
-  /**
-   * Absolute site origin for sitemap/robots URLs. Falls back to
-   * NEXT_PUBLIC_SERVER_URL, then to a relative origin (which most crawlers
-   * reject, so set one in production).
-   */
-  baseUrl?: string
   /**
    * The client's payload config promise (the default export of payload.config).
    * Passed in because the plugin never imports the client's config directly.
@@ -24,15 +16,21 @@ type CreateContentHelpersArgs = {
   config: Promise<SanitizedConfig> | SanitizedConfig
   /** Archive-backed collections, same value as the plugin option. */
   content?: ContentOption
+  /** SiteSettings global slug. Defaults to 'site-settings'. */
+  settingsSlug?: string
+  /** Pages collection slug. Defaults to 'pages'. */
+  pagesSlug?: string
   /**
    * i18n config. Required only if you want the ready-made `sitemap` / `robots`
    * handlers — they need the locale list to emit hreflang.
    */
   i18n?: I18nConfig
-  /** Pages collection slug. Defaults to 'pages'. */
+  /**
-  pagesSlug?: string
+   * Absolute site origin for sitemap/robots URLs. Falls back to
-  /** SiteSettings global slug. Defaults to 'site-settings'. */
+   * NEXT_PUBLIC_SERVER_URL, then to a relative origin (which most crawlers
-  settingsSlug?: string
+   * reject, so set one in production).
+   */
+  baseUrl?: string
 }
 
 /**
@@ -62,12 +60,12 @@ type CreateContentHelpersArgs = {
  * not the second, and a page component composes them in two obvious lines.
  */
 export function createContentHelpers({
-  baseUrl,
   config,
   content,
-  i18n,
-  pagesSlug = 'pages',
   settingsSlug = 'site-settings',
+  pagesSlug = 'pages',
+  i18n,
+  baseUrl,
 }: CreateContentHelpersArgs) {
   const origin = baseUrl ?? process.env.NEXT_PUBLIC_SERVER_URL ?? ''
   const getCachedPayload = cache(async (): Promise<BasePayload> =>
@@ -81,7 +79,7 @@ export function createContentHelpers({
 
   const getSettings = cache(async (locale: string) => {
     const payload = await getCachedPayload()
-    return payload.findGlobal({ slug: settingsSlug as never, depth: 2, locale: locale as never })
+    return payload.findGlobal({ slug: settingsSlug as never, locale: locale as never, depth: 2 })
   })
 
   /** What does this URL point at? Routing only — no listing data. */
@@ -90,9 +88,9 @@ export function createContentHelpers({
       locale: string,
       segments: string[] | undefined,
       page: number,
-    ): Promise<null | ResolvedRoute> => {
+    ): Promise<ResolvedRoute | null> => {
       const payload = await getCachedPayload()
-      return resolveRouteRaw({ content, locale, page, pagesSlug, payload, segments, settingsSlug })
+      return resolveRouteRaw({ payload, locale, segments, page, content, pagesSlug, settingsSlug })
     },
   )
 
@@ -105,7 +103,7 @@ export function createContentHelpers({
       perPage: number,
     ): Promise<ArchiveEntries> => {
       const payload = await getCachedPayload()
-      return getArchiveEntries({ collection, locale, page, payload, perPage })
+      return getArchiveEntries({ payload, collection, locale, page, perPage })
     },
   )
 
@@ -116,20 +114,45 @@ export function createContentHelpers({
    * ```ts
    * // app/sitemap.ts
    * export { sitemap as default } from '@/lib/content'
+   * export const dynamic = 'force-dynamic'  // generate at runtime, not build
    * ```
+   *
+   * IMPORTANT — container deploys (Coolify/Docker/Railway/CI): Next treats
+   * sitemap.ts as STATIC by default and prerenders it during `next build`, which
+   * calls into Payload → the database. The build container usually has no access
+   * to the internal Docker network, so the DB connection fails (ENOTFOUND) and
+   * the build dies. Two defenses:
+   *   1. `export const dynamic = 'force-dynamic'` in app/sitemap.ts — skips build
+   *      prerender, generates at runtime when the DB is reachable (recommended).
+   *   2. This handler also catches DB errors and returns [] so that even without
+   *      (1) the build won't crash — it just ships an empty sitemap until the
+   *      next runtime regeneration. (1) is still preferred; (2) is a safety net.
    */
   const sitemap = cache(async (): Promise<SitemapEntry[]> => {
     if (!i18n) {
       throw new Error('[ipal] createContentHelpers: pass `i18n` to use the sitemap handler.')
     }
-    return buildSitemapEntries({
+    try {
-      baseUrl: origin,
+      return await buildSitemapEntries({
+        payload: await getCachedPayload(),
         config: i18n,
+        baseUrl: origin,
         content,
         pagesSlug,
-      payload: await getCachedPayload(),
         settingsSlug,
       })
+    } catch (error) {
+      // DB unreachable (typically a container build with no DB network) — return
+      // an empty sitemap instead of failing the build. Runtime regeneration will
+      // produce the real one once the DB is reachable. See dynamic='force-dynamic'.
+      console.warn(
+        '[ipal] sitemap: could not reach the database, returning empty entries ' +
+          "(add `export const dynamic = 'force-dynamic'` to app/sitemap.ts to " +
+          'generate at runtime and avoid build-time DB access):',
+        error,
+      )
+      return []
+    }
   })
 
   /**
@@ -145,10 +168,10 @@ export function createContentHelpers({
   return {
     getCachedPayload,
     getConfiguredLocales,
-    getEntries,
     getSettings,
     resolveRoute,
-    robots,
+    getEntries,
     sitemap,
+    robots,
   }
 }

src/modules/seo/buildBreadcrumbJsonLd.ts

@@ -0,0 +1,44 @@
+type Crumb = {
+  /** Visible name of the breadcrumb (e.g. 'Usługi'). */
+  name: string
+  /** Absolute URL of this crumb (e.g. 'https://example.com/pl/uslugi'). */
+  url: string
+}
+
+/**
+ * Builds BreadcrumbList JSON-LD (schema.org) for a page's position in the site
+ * hierarchy. Google can show breadcrumbs in the result (Dom › Usługi › Detailing)
+ * and uses them to understand structure — a signal that helps navigational
+ * results and sitelinks.
+ *
+ * Unlike Organization/WebSite (site-wide, root layout), breadcrumbs are
+ * PER-PAGE — build them from the page's ancestry and emit on that page:
+ *
+ *   import { buildBreadcrumbJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildBreadcrumbJsonLd([
+ *     { name: 'Strona główna', url: `${base}/pl` },
+ *     { name: 'Usługi', url: `${base}/pl/uslugi` },
+ *     { name: 'Detailing', url: `${base}/pl/uslugi/detailing` },
+ *   ])
+ *   <script type="application/ld+json" ... />
+ *
+ * The crumb data comes from the page's real position (parent pages / URL path),
+ * NOT hardcoded. Derive it from the resolved route, not a static list.
+ *
+ * Returns null for an empty/single crumb list — a one-item breadcrumb isn't
+ * meaningful and shouldn't be emitted.
+ */
+export function buildBreadcrumbJsonLd(crumbs: Crumb[]) {
+  if (!crumbs || crumbs.length < 2) {return null}
+
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'BreadcrumbList',
+    itemListElement: crumbs.map((crumb, index) => ({
+      name: crumb.name,
+      '@type': 'ListItem',
+      item: crumb.url,
+      position: index + 1,
+    })),
+  }
+}

src/modules/seo/buildFaqJsonLd.ts

@@ -0,0 +1,37 @@
+type FaqItem = {
+  answer: string
+  question: string
+}
+
+/**
+ * Builds FAQPage JSON-LD (schema.org) from Q&A pairs. Google can show these as
+ * expandable FAQ rich results under the page, taking more SERP space and helping
+ * with voice/AI answers. Strong for service landing pages.
+ *
+ * Feed it the SAME questions/answers rendered on the page (from an FAQ block in
+ * the panel) — the structured data must match visible content, or Google may
+ * flag it. Never invent Q&A that isn't on the page.
+ *
+ *   import { buildFaqJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildFaqJsonLd(
+ *     faqBlock.items.map(i => ({ question: i.question, answer: i.answer }))
+ *   )
+ *
+ * Returns null for empty list.
+ */
+export function buildFaqJsonLd(items: FaqItem[]) {
+  if (!items || items.length === 0) {return null}
+
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'FAQPage',
+    mainEntity: items.map((item) => ({
+      name: item.question,
+      '@type': 'Question',
+      acceptedAnswer: {
+        '@type': 'Answer',
+        text: item.answer,
+      },
+    })),
+  }
+}

src/modules/seo/buildIconsMetadata.ts

@@ -0,0 +1,46 @@
+import type { Metadata } from 'next'
+
+type MediaLike =
+  | { height?: null | number; mimeType?: null | string; url?: null | string; width?: null | number }
+  | null
+  | undefined
+
+/**
+ * Builds Next.js `icons` metadata (favicon / apple-touch-icon) from the panel's
+ * favicon upload, so the browser tab AND Google get a proper <link rel="icon">.
+ *
+ * Why the plugin must do this (not the project): favicon-in-Google has strict
+ * rules — a real <link rel="icon"> in <head>, square, ≥48×48, at a stable URL.
+ * Leaving it to each project meant inconsistent hand-rolled tags and no favicon
+ * in search results. This generates the tags correctly, every time, from the
+ * panel field.
+ *
+ * Favicon is GLOBAL (same across pages), so call this once in the ROOT layout's
+ * generateMetadata — not per page:
+ *
+ *   import { buildIconsMetadata } from '@intecion/ipal-kit'
+ *   export async function generateMetadata(): Promise<Metadata> {
+ *     const settings = await getSettings(locale)
+ *     return buildIconsMetadata(settings.favicon)
+ *   }
+ *
+ * Google notes: it caches favicons separately and slowly (days/weeks), and only
+ * shows them for icons it deems valid. Warn on too-small icons at upload time
+ * (see the media validation hook) so editors don't ship a <48px favicon Google
+ * will reject.
+ */
+export function buildIconsMetadata(favicon: MediaLike): Metadata {
+  const url = favicon?.url
+  if (!url) {return {}}
+
+  const isSvg = favicon?.mimeType === 'image/svg+xml' || url.endsWith('.svg')
+
+  return {
+    icons: {
+      // Main favicon. SVG scales; PNG should be ≥48×48 (ideally 96 or 192).
+      icon: isSvg ? [{ type: 'image/svg+xml', url }] : [{ sizes: 'any', url }],
+      // Apple touch icon (home-screen bookmark on iOS). Reuses the same asset.
+      apple: [{ url }],
+    },
+  }
+}

src/modules/seo/buildLocalBusinessJsonLd.ts

@@ -0,0 +1,86 @@
+type MediaLike = { url?: null | string } | null | undefined
+
+type Address = {
+  city?: string
+  country?: string // ISO code, e.g. 'PL'
+  postalCode?: string
+  region?: string
+  street?: string
+}
+
+type LocalBusinessJsonLdArgs = {
+  address?: Address
+  /** Geo coordinates for maps/local search. */
+  geo?: { latitude: number; longitude: number }
+  image?: MediaLike
+  logo?: MediaLike
+  name: string
+  /** Opening hours, e.g. ['Mo-Fr 08:00-18:00', 'Sa 09:00-14:00']. */
+  openingHours?: string[]
+  priceRange?: string // e.g. '$$'
+  sameAs?: string[]
+  /** Business phone, e.g. '+48 123 456 789'. */
+  telephone?: string
+  url: string
+}
+
+/**
+ * Builds LocalBusiness JSON-LD (schema.org) — the key structured data for LOCAL
+ * SEO. Helps Google show the business in local results / map pack with address,
+ * hours, phone. Strong signal for "usługa + miasto" queries.
+ *
+ * All data from the panel (company global) — nothing hardcoded. Emit once in the
+ * root layout (business is site-wide):
+ *
+ *   import { buildLocalBusinessJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildLocalBusinessJsonLd({
+ *     name: company.name, url: baseUrl, telephone: company.phone,
+ *     address: company.address, openingHours: company.hours,
+ *   })
+ *
+ * For a more specific type (e.g. 'Dentist', 'Plumber'), override @type in the
+ * returned object — schema.org has many LocalBusiness subtypes.
+ */
+export function buildLocalBusinessJsonLd({
+  name,
+  address,
+  geo,
+  image,
+  logo,
+  openingHours,
+  priceRange,
+  sameAs,
+  telephone,
+  url,
+}: LocalBusinessJsonLdArgs) {
+  const logoUrl = logo?.url
+  const imageUrl = image?.url ?? logoUrl
+
+  return {
+    name,
+    '@context': 'https://schema.org',
+    '@type': 'LocalBusiness',
+    url,
+    ...(telephone ? { telephone } : {}),
+    ...(imageUrl ? { image: imageUrl.startsWith('http') ? imageUrl : `${url}${imageUrl}` } : {}),
+    ...(logoUrl ? { logo: logoUrl.startsWith('http') ? logoUrl : `${url}${logoUrl}` } : {}),
+    ...(address
+      ? {
+          address: {
+            '@type': 'PostalAddress',
+            ...(address.street ? { streetAddress: address.street } : {}),
+            ...(address.city ? { addressLocality: address.city } : {}),
+            ...(address.postalCode ? { postalCode: address.postalCode } : {}),
+            ...(address.region ? { addressRegion: address.region } : {}),
+            ...(address.country ? { addressCountry: address.country } : {}),
+          },
+        }
+      : {}),
+    ...(geo
+      ? { geo: { '@type': 'GeoCoordinates', latitude: geo.latitude, longitude: geo.longitude } }
+      : {}),
+    ...(openingHours && openingHours.length > 0 ? { openingHours } : {}),
+    ...(priceRange ? { priceRange } : {}),
+    ...(sameAs && sameAs.length > 0 ? { sameAs } : {}),
+  }
+}

src/modules/seo/buildMetadata.ts

@@ -22,6 +22,11 @@ export type PageMetadata = {
     locale?: string
     title: string
   }
+  /** robots directives — set to noindex/follow for legal/thin/search pages. */
+  robots?: {
+    follow: boolean
+    index: boolean
+  }
   title: string
 }
 
@@ -39,6 +44,13 @@ type BuildMetadataArgs = {
   meta?: null | SeoMeta
   /** Page title or site name first. Defaults to 'page-first'. */
   order?: TitleOrder
+  /**
+   * The document's own title (e.g. page.title = 'Sprzątanie biur'). Used as the
+   * page-title source when meta.title is empty — the browser tab and search
+   * result should show the page name, not go blank, when an editor didn't fill
+   * the SEO title. Priority: titleOverride > meta.title > pageTitle.
+   */
+  pageTitle?: null | string
   /**
    * Localized segment the document lives under (an archive page's slugs).
    * Feeds both canonical and hreflang, so /pl/artykuly/moj-post and
@@ -78,16 +90,21 @@ export function buildMetadata({
   locale,
   meta,
   order,
+  pageTitle,
   prefix,
   query,
   separator,
   siteName,
   slugs,
 }: BuildMetadataArgs): PageMetadata {
-  // titleOverride wins outright: an editor who filled it in wants that exact
+  // Title source priority: titleOverride (exact, wins outright) > meta.title
-  // string in the tab, not a composition.
+  // (SEO title an editor set) > pageTitle (the document's own name). This means
+  // a page with no SEO title still shows its name (e.g. 'Sprzątanie biur')
+  // composed with the site name, instead of just the site name or a blank.
   const override = meta?.titleOverride?.trim()
-  const title = override || composeTitle({ order, pageTitle: meta?.title, separator, siteName })
+  const resolvedPageTitle = meta?.title?.trim() || pageTitle?.trim() || undefined
+  const title =
+    override || composeTitle({ order, pageTitle: resolvedPageTitle, separator, siteName })
   const description = meta?.description?.trim() || undefined
   const origin = baseUrl?.replace(/\/$/, '') ?? ''
 
@@ -118,5 +135,8 @@ export function buildMetadata({
       ...(images && { images }),
       locale,
     },
+    // noindex → tell search engines to exclude the page but still follow links
+    // (authority flows through). For legal/thin/search-result pages.
+    ...(meta?.noindex ? { robots: { follow: true, index: false } } : {}),
   }
 }

src/modules/seo/buildOrganizationJsonLd.ts

@@ -0,0 +1,44 @@
+type MediaLike = { url?: null | string } | null | undefined
+
+type OrganizationJsonLdArgs = {
+  /** Logo media (from panel). Google uses this for brand knowledge panels. */
+  logo?: MediaLike
+  /** Organization / site name. */
+  name: string
+  /** Optional social / official profile URLs (sameAs). */
+  sameAs?: string[]
+  /** Absolute site URL (https://…). */
+  url: string
+}
+
+/**
+ * Builds Organization JSON-LD (schema.org) — helps Google associate the site
+ * with a brand: name, logo, official links. Improves how the site appears in
+ * search (brand recognition, logo in knowledge panels) and is a signal used
+ * alongside favicon for identity.
+ *
+ * Returns a plain object; the project renders it as a <script type="application/
+ * ld+json"> in the root layout:
+ *
+ *   import { buildOrganizationJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildOrganizationJsonLd({
+ *     name: settings.siteName, url: baseUrl, logo: settings.logo,
+ *   })
+ *   <script type="application/ld+json"
+ *     dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }} />
+ *
+ * Data comes from the panel (siteName, logo) — nothing hardcoded. Emit once in
+ * the root layout (Organization is site-wide, not per page).
+ */
+export function buildOrganizationJsonLd({ name, logo, sameAs, url }: OrganizationJsonLdArgs) {
+  const logoUrl = logo?.url
+
+  return {
+    name,
+    '@context': 'https://schema.org',
+    '@type': 'Organization',
+    url,
+    ...(logoUrl ? { logo: logoUrl.startsWith('http') ? logoUrl : `${url}${logoUrl}` } : {}),
+    ...(sameAs && sameAs.length > 0 ? { sameAs } : {}),
+  }
+}

src/modules/seo/buildServiceJsonLd.ts

@@ -0,0 +1,48 @@
+type ServiceJsonLdArgs = {
+  /** Area served, e.g. 'Wrocław' or ['Wrocław', 'Oława']. */
+  areaServed?: string | string[]
+  description?: string
+  /** Service name, e.g. 'Sprzątanie biur'. */
+  name: string
+  /** Provider (business) name. */
+  providerName: string
+  /** Service type / category. */
+  serviceType?: string
+  url: string
+}
+
+/**
+ * Builds Service JSON-LD (schema.org) for a service offering. Helps Google
+ * understand "what this page sells" — useful for service landing pages
+ * ("usługa + miasto"). Pairs well with LocalBusiness (the provider).
+ *
+ * Per-page (each service page emits its own), data from the panel:
+ *
+ *   import { buildServiceJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildServiceJsonLd({
+ *     name: page.serviceName, providerName: company.name,
+ *     url: pageUrl, areaServed: 'Wrocław',
+ *   })
+ */
+export function buildServiceJsonLd({
+  name,
+  areaServed,
+  description,
+  providerName,
+  serviceType,
+  url,
+}: ServiceJsonLdArgs) {
+  return {
+    name,
+    '@context': 'https://schema.org',
+    '@type': 'Service',
+    provider: {
+      name: providerName,
+      '@type': 'LocalBusiness',
+      url,
+    },
+    ...(description ? { description } : {}),
+    ...(areaServed ? { areaServed } : {}),
+    ...(serviceType ? { serviceType } : {}),
+  }
+}

src/modules/seo/buildSiteNavigationJsonLd.ts

@@ -0,0 +1,39 @@
+type NavItem = {
+  /** Visible label (e.g. 'Usługi'). */
+  name: string
+  /** Absolute URL (e.g. 'https://example.com/pl/uslugi'). */
+  url: string
+}
+
+/**
+ * Builds SiteNavigationElement JSON-LD (schema.org) from the main navigation —
+ * declares the site's primary nav as structured data. A weaker sitelinks signal
+ * than WebSite/breadcrumbs, but cheap: it tells Google which pages are the main
+ * navigation targets.
+ *
+ * Feed it the SAME nav items the header renders (from the panel/nav global), so
+ * the structured data matches the visible menu — not a separate hardcoded list.
+ *
+ *   import { buildSiteNavigationJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildSiteNavigationJsonLd(
+ *     navItems.map(i => ({ name: i.label, url: `${base}${i.href}` }))
+ *   )
+ *   <script type="application/ld+json" ... />
+ *
+ * Emit once (site-wide, root layout). Data from the nav source, never hardcoded.
+ * Returns null for empty nav.
+ */
+export function buildSiteNavigationJsonLd(items: NavItem[]) {
+  if (!items || items.length === 0) {return null}
+
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'ItemList',
+    itemListElement: items.map((item, index) => ({
+      name: item.name,
+      '@type': 'SiteNavigationElement',
+      position: index + 1,
+      url: item.url,
+    })),
+  }
+}

src/modules/seo/buildSitemapEntries.ts

@@ -1,11 +1,10 @@
 import type { BasePayload } from 'payload'
-
-import type { ContentOption } from '../content/index.js'
 import type { I18nConfig } from '../i18n/index.js'
-
+import { getLocalizedSlugs } from '../i18n/index.js'
-import { archiveFieldName } from '../content/index.js'
+import { buildLocalizedPath } from '../i18n/index.js'
-import { buildLocalizedPath, getLocalizedSlugs  } from '../i18n/index.js'
 import { buildHreflangAlternates } from './hreflang.js'
+import type { ContentOption } from '../content/index.js'
+import { archiveFieldName } from '../content/index.js'
 
 /**
  * One sitemap entry, shaped for Next's `app/sitemap.ts`.
@@ -16,50 +15,70 @@ import { buildHreflangAlternates } from './hreflang.js'
  * is the common, weaker kind.
  */
 export type SitemapEntry = {
-  alternates?: { languages: Record<string, string> }
-  changeFrequency?: 'always' | 'daily' | 'hourly' | 'monthly' | 'never' | 'weekly' | 'yearly'
-  lastModified?: Date | string
-  priority?: number
   url: string
+  lastModified?: string | Date
+  changeFrequency?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never'
+  priority?: number
+  alternates?: { languages: Record<string, string> }
 }
 
 type CollectionEntry = {
+  slug: string
   /** Localized segment for entries (archive page slugs), when applicable. */
   prefixSlugs?: Record<string, string>
-  slug: string
 }
 
 type BuildSitemapArgs = {
+  payload: BasePayload
+  config: I18nConfig
   /** Absolute origin, e.g. 'https://example.com'. Required for valid sitemap URLs. */
   baseUrl: string
-  changeFrequency?: SitemapEntry['changeFrequency']
+  /** Pages collection slug. Defaults to 'pages'. */
-  config: I18nConfig
+  pagesSlug?: string
   /** Archive-backed collections, same value as the plugin option. */
   content?: ContentOption
+  /** SiteSettings global slug. Defaults to 'site-settings'. */
+  settingsSlug?: string
   /**
    * Slug of the page that is the site root (collapses to /{locale}).
    * Read from System Pages when omitted.
    */
   homeSlug?: string
-  /** Pages collection slug. Defaults to 'pages'. */
+  changeFrequency?: SitemapEntry['changeFrequency']
-  pagesSlug?: string
-  payload: BasePayload
-  /** SiteSettings global slug. Defaults to 'site-settings'. */
-  settingsSlug?: string
 }
 
 type DocRow = {
-  _status?: string
+  id: string | number
-  id: number | string
-  meta?: { noindex?: boolean } | null
   slug?: unknown
   updatedAt?: string
+  _status?: string
+  meta?: { noindex?: boolean } | null
 }
 
-/** Skip drafts and anything flagged noindex in the SEO tab. */
+/**
+ * Slugs that must never appear in the sitemap — error/system pages that exist as
+ * documents (e.g. a '404' page in the Pages collection) but should not be
+ * indexed. A sitemap should list only real, HTTP-200 content; a '/pl/404' entry
+ * is an audit finding. Matched against the slug in any locale.
+ */
+const EXCLUDED_SITEMAP_SLUGS = new Set(['404', '500', 'not-found', 'error'])
+
+/** True if the doc's slug (in any locale) is an excluded system/error slug. */
+function hasExcludedSlug(slug: unknown): boolean {
+  if (typeof slug === 'string') return EXCLUDED_SITEMAP_SLUGS.has(slug)
+  if (slug && typeof slug === 'object') {
+    for (const value of Object.values(slug as Record<string, unknown>)) {
+      if (typeof value === 'string' && EXCLUDED_SITEMAP_SLUGS.has(value)) return true
+    }
+  }
+  return false
+}
+
+/** Skip drafts, noindex, and system/error pages (404 etc.). */
 function isIndexable(doc: DocRow): boolean {
-  if (doc._status && doc._status !== 'published') {return false}
+  if (doc._status && doc._status !== 'published') return false
-  if (doc.meta?.noindex) {return false}
+  if (doc.meta?.noindex) return false
+  if (hasExcludedSlug(doc.slug)) return false
   return true
 }
 
@@ -77,17 +96,17 @@ function entryFor(
   homeSlug: string | undefined,
   prefix: Record<string, string> | undefined,
   changeFrequency: SitemapEntry['changeFrequency'],
-): null | SitemapEntry {
+): SitemapEntry | null {
   const slugs =
     doc.slug && typeof doc.slug === 'object'
-      ? getLocalizedSlugs({ config, slugField: doc.slug as Record<string, unknown> })
+      ? getLocalizedSlugs({ slugField: doc.slug as Record<string, unknown>, config })
       : {}
 
-  const path = buildLocalizedPath({ config, homeSlug, locale, prefix, slugs })
+  const path = buildLocalizedPath({ slugs, locale, config, homeSlug, prefix })
-  if (!path) {return null}
+  if (!path) return null
 
   const origin = baseUrl.replace(/\/$/, '')
-  const languages = buildHreflangAlternates({ baseUrl, config, homeSlug, prefix, slugs })
+  const languages = buildHreflangAlternates({ slugs, config, baseUrl, homeSlug, prefix })
 
   return {
     url: `${origin}${path}`,
@@ -119,14 +138,14 @@ function entryFor(
  * ```
  */
 export async function buildSitemapEntries({
-  baseUrl,
-  changeFrequency = 'weekly',
-  config,
-  content,
-  homeSlug,
-  pagesSlug = 'pages',
   payload,
+  config,
+  baseUrl,
+  pagesSlug = 'pages',
+  content,
   settingsSlug = 'site-settings',
+  homeSlug,
+  changeFrequency = 'weekly',
 }: BuildSitemapArgs): Promise<SitemapEntry[]> {
   const locales = config.locales.map((l) => l.code)
   const defaultLocale = config.defaultLocale
@@ -135,8 +154,8 @@ export async function buildSitemapEntries({
   // locales so archive prefixes are available per language).
   const settings = (await payload.findGlobal({
     slug: settingsSlug as never,
-    depth: 1,
     locale: 'all' as never,
+    depth: 1,
   })) as Record<string, unknown>
 
   const resolvedHomeSlug =
@@ -159,14 +178,14 @@ export async function buildSitemapEntries({
     // alternates without re-querying per locale.
     const result = await payload.find({
       collection: collection.slug as never,
+      locale: 'all' as never,
       depth: 0,
       limit: 0, // no pagination — sitemap wants everything
-      locale: 'all' as never,
       pagination: false as never,
     })
 
     for (const raw of result.docs as DocRow[]) {
-      if (!isIndexable(raw)) {continue}
+      if (!isIndexable(raw)) continue
 
       // Emit the entry under the default locale's URL; alternates cover the rest.
       const entry = entryFor(
@@ -178,7 +197,7 @@ export async function buildSitemapEntries({
         collection.prefixSlugs,
         changeFrequency,
       )
-      if (entry) {entries.push(entry)}
+      if (entry) entries.push(entry)
     }
   }
 
@@ -187,9 +206,9 @@ export async function buildSitemapEntries({
 
 /** Pulls a slug string from a populated relationship in a specific locale. */
 function extractSlugInLocale(rel: unknown, locale: string): string | undefined {
-  if (!rel || typeof rel !== 'object') {return undefined}
+  if (!rel || typeof rel !== 'object') return undefined
   const slug = (rel as { slug?: unknown }).slug
-  if (typeof slug === 'string') {return slug}
+  if (typeof slug === 'string') return slug
   if (slug && typeof slug === 'object') {
     const v = (slug as Record<string, unknown>)[locale]
     return typeof v === 'string' ? v : undefined
@@ -199,14 +218,14 @@ function extractSlugInLocale(rel: unknown, locale: string): string | undefined {
 
 /** Builds a locale→slug map from a populated archive relationship. */
 function slugMapAllLocales(rel: unknown, locales: string[]): Record<string, string> | undefined {
-  if (!rel || typeof rel !== 'object') {return undefined}
+  if (!rel || typeof rel !== 'object') return undefined
   const slug = (rel as { slug?: unknown }).slug
-  if (!slug || typeof slug !== 'object') {return undefined}
+  if (!slug || typeof slug !== 'object') return undefined
 
   const map: Record<string, string> = {}
   for (const locale of locales) {
     const v = (slug as Record<string, unknown>)[locale]
-    if (typeof v === 'string') {map[locale] = v}
+    if (typeof v === 'string') map[locale] = v
   }
   return Object.keys(map).length ? map : undefined
 }

src/modules/seo/buildWebSiteJsonLd.ts

@@ -0,0 +1,62 @@
+type SearchActionConfig = {
+  /**
+   * URL template for site search, with {search_term_string} placeholder.
+   * e.g. 'https://example.com/szukaj?q={search_term_string}'. Only include if
+   * the site actually HAS a working search page — a SearchAction pointing at a
+   * non-existent search does more harm than good.
+   */
+  target: string
+}
+
+type WebSiteJsonLdArgs = {
+  /** Site name (from panel — siteName). */
+  name: string
+  /**
+   * Optional site search. Enables the "sitelinks searchbox" — a search field
+   * Google may show under the brand result. Only pass when a real search page
+   * exists. Omit entirely otherwise.
+   */
+  search?: SearchActionConfig
+  /** Absolute site URL (https://…). */
+  url: string
+}
+
+/**
+ * Builds WebSite JSON-LD (schema.org). Two jobs:
+ *  - Declares the site + name (helps Google associate brand queries with the site).
+ *  - Optionally declares a SearchAction, which is what can produce the "sitelinks
+ *    searchbox" (a search field under the brand result in Google).
+ *
+ * IMPORTANT — sitelinks (the sub-links under a result) CANNOT be forced. No
+ * schema guarantees them; Google generates them algorithmically from site
+ * structure, internal links, clear titles, and ranking. This schema is a SIGNAL
+ * that improves the odds and can enable the searchbox — not a switch. Manage
+ * expectations accordingly (see docs/seo.md).
+ *
+ * Emit once in the ROOT layout (site-wide), from panel data:
+ *
+ *   import { buildWebSiteJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildWebSiteJsonLd({ name: settings.siteName, url: baseUrl })
+ *   <script type="application/ld+json"
+ *     dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }} />
+ */
+export function buildWebSiteJsonLd({ name, search, url }: WebSiteJsonLdArgs) {
+  return {
+    name,
+    '@context': 'https://schema.org',
+    '@type': 'WebSite',
+    url,
+    ...(search
+      ? {
+          potentialAction: {
+            '@type': 'SearchAction',
+            'query-input': 'required name=search_term_string',
+            target: {
+              '@type': 'EntryPoint',
+              urlTemplate: search.target,
+            },
+          },
+        }
+      : {}),
+  }
+}

src/modules/seo/createPageMetadata.ts

@@ -43,6 +43,8 @@ type PageMetadataContext = {
 type DocShape = {
   id: number | string
   meta?: null | SeoMeta
+  /** The document's own title (page name), used as the fallback page title. */
+  title?: null | string
 }
 
 /** plugin-seo stores the OG image as an upload relationship. */
@@ -151,6 +153,7 @@ export function createPageMetadata(args: CreatePageMetadataArgs) {
       ...base,
       imageUrl: resolveOgImage(doc),
       meta: doc.meta,
+      pageTitle: doc.title,
       prefix,
       query,
       slugs,

src/modules/seo/hreflang.ts

@@ -1,6 +1,6 @@
 import type { I18nConfig, LocalizedSlugs } from '../i18n/index.js'
 
-import { buildLocalizedPath, getLocaleCodes } from '../i18n/index.js'
+import { buildLocalizedPath, getDefaultLocale, getLocaleCodes } from '../i18n/index.js'
 
 type BuildHreflangArgs = {
   /** Absolute site origin, e.g. 'https://example.com'. Omit for relative paths. */
@@ -19,20 +19,28 @@ type BuildHreflangArgs = {
 }
 
 /**
- * Builds a map of locale → URL for hreflang alternate links, suitable for
  * Next.js Metadata `alternates.languages`.
  *
  * Bridges SEO and i18n: for each configured locale that the document has a
  * slug in, it produces the locale-aware path (via buildLocalizedPath),
  * optionally prefixed with an absolute origin.
  *
+ * Also emits `x-default` pointing at the default locale — the version Google
+ * serves when the user's language/region matches no hreflang, and the fallback
+ * when the root ('/') redirect is ambiguous (Googlebot with no/foreign
+ * Accept-Language).
+ *
  * @example
  * buildHreflangAlternates({
  *   slugs: { pl: 'o-nas', en: 'about' },
  *   config,
  *   baseUrl: 'https://example.com',
  * })
- * // → { pl: 'https://example.com/pl/o-nas', en: 'https://example.com/en/about' }
+ * // → {
+ * //   pl: 'https://example.com/pl/o-nas',
+ * //   en: 'https://example.com/en/about',
+ * //   'x-default': 'https://example.com/pl/o-nas',
+ * // }
  */
 export function buildHreflangAlternates({
   baseUrl,
@@ -51,5 +59,15 @@ export function buildHreflangAlternates({
     }
   }
 
+  // x-default: the version Google serves when the user's language/region doesn't
+  // match any hreflang — and, crucially here, the fallback when the root ('/')
+  // redirect is ambiguous (Googlebot with no/foreign Accept-Language). Point it
+  // at the default locale (the primary market) so search shows that version by
+  // default instead of guessing. Only set when the default locale has a URL.
+  const defaultLocalePath = alternates[getDefaultLocale(config)]
+  if (defaultLocalePath) {
+    alternates['x-default'] = defaultLocalePath
+  }
+
   return alternates
 }

src/modules/seo/index.ts

@@ -1,11 +1,19 @@
 export { buildAutoFillMetaHook } from './autoFillMeta.js'
 export type { AutoFillMapping } from './autoFillMeta.js'
+export { buildBreadcrumbJsonLd } from './buildBreadcrumbJsonLd.js'
+export { buildFaqJsonLd } from './buildFaqJsonLd.js'
+export { buildIconsMetadata } from './buildIconsMetadata.js'
+export { buildLocalBusinessJsonLd } from './buildLocalBusinessJsonLd.js'
 export { buildMetadata } from './buildMetadata.js'
 export type { PageMetadata } from './buildMetadata.js'
+export { buildOrganizationJsonLd } from './buildOrganizationJsonLd.js'
 export { buildRobots } from './buildRobots.js'
 export type { RobotsRules } from './buildRobots.js'
+export { buildServiceJsonLd } from './buildServiceJsonLd.js'
 export { buildSitemapEntries } from './buildSitemapEntries.js'
 export type { SitemapEntry } from './buildSitemapEntries.js'
+export { buildSiteNavigationJsonLd } from './buildSiteNavigationJsonLd.js'
+export { buildWebSiteJsonLd } from './buildWebSiteJsonLd.js'
 export { composeTitle } from './composeTitle.js'
 export type { TitleOrder } from './composeTitle.js'
 export { createMetadataGenerator } from './createMetadataGenerator.js'
@@ -18,3 +26,4 @@ export type { SiteMetaConfig } from './readSiteMetaConfig.js'
 export { buildSeoPlugin } from './seoPluginConfig.js'
 export { slugsAcrossLocales } from './slugsAcrossLocales.js'
 export type { SeoMeta, SeoOption } from './types.js'
+export { validateFaviconField } from './validateFavicon.js'

src/modules/seo/types.ts

@@ -33,6 +33,7 @@ export type SeoOption = {
 export type SeoMeta = {
   description?: null | string
   image?: unknown
+  noindex?: boolean | null
   title?: null | string
   /** When set, used as the whole title — no site name, no separator. */
   titleOverride?: null | string

src/modules/seo/validateFavicon.ts

@@ -0,0 +1,52 @@
+import type { FieldHook } from 'payload'
+
+/**
+ * Field validation for the favicon upload: Google rejects favicons under 48×48,
+ * so warn the editor at save time if the uploaded icon is too small or not
+ * square. This ENFORCES the requirement instead of silently shipping a favicon
+ * Google won't display.
+ *
+ * Attach to the favicon field's validate (or as a beforeValidate hook on the
+ * Media relationship). Non-blocking by default — returns a warning string that
+ * Payload surfaces; make it throw if you want a hard block.
+ *
+ * Note: dimensions come from the related Media doc (Payload stores width/height
+ * for image uploads), so this checks the resolved upload, not the raw file.
+ */
+export const validateFaviconField: FieldHook = async ({ req, value }) => {
+  if (!value) {return value} // no favicon set → nothing to validate (optional field)
+
+  try {
+    const media = await req.payload.findByID({
+      id: typeof value === 'object' ? (value as { id: string }).id : value,
+      collection: 'media',
+      depth: 0,
+    })
+
+    const width = (media as { width?: number }).width
+    const height = (media as { height?: number }).height
+    const mimeType = (media as { mimeType?: string }).mimeType
+
+    // SVG scales infinitely — skip size checks.
+    if (mimeType === 'image/svg+xml') {return value}
+
+    if (typeof width === 'number' && typeof height === 'number') {
+      if (width < 48 || height < 48) {
+        req.payload.logger.warn(
+          `[ipal] Favicon is ${width}×${height}px. Google requires ≥48×48 to ` +
+            `display it in search results. Upload a larger square icon (96 or 192px).`,
+        )
+      }
+      if (width !== height) {
+        req.payload.logger.warn(
+          `[ipal] Favicon is not square (${width}×${height}). Use a square icon ` +
+            `so it isn't cropped in the browser tab or search results.`,
+        )
+      }
+    }
+  } catch {
+    // Media lookup failed — don't block the save over a validation warning.
+  }
+
+  return value
+}

src/modules/storage/MediaPreconnect.tsx

@@ -0,0 +1,38 @@
+/**
+ * Emits <link rel="preconnect"> + <link rel="dns-prefetch"> for the media CDN
+ * domain (R2_PUBLIC_URL), so the browser opens the TLS/DNS connection to the
+ * media host early — before it hits the first <img>. Saves ~150–300ms on the
+ * first image load.
+ *
+ * Reads the domain from R2_PUBLIC_URL (the same env var buildR2Storage uses),
+ * so there's ONE source of truth — no per-project hardcoded domain. Renders
+ * nothing when R2_PUBLIC_URL isn't set (local disk / no CDN → nothing to
+ * preconnect).
+ *
+ * Server Component — drop it in the <head> of your locale layout:
+ *
+ *   import { MediaPreconnect } from '@intecion/ipal-kit/rsc'
+ *   // in <head> (or top of <body> — Next hoists link tags):
+ *   <MediaPreconnect />
+ */
+export function MediaPreconnect() {
+  const publicUrl = process.env.R2_PUBLIC_URL?.replace(/\/$/, '')
+  if (!publicUrl) {return null}
+
+  // Origin only (scheme + host) — preconnect targets an origin, not a path.
+  let origin: string
+  try {
+    origin = new URL(publicUrl).origin
+  } catch {
+    return null // malformed URL → skip rather than emit a broken tag
+  }
+
+  return (
+    <>
+      <link crossOrigin="anonymous" href={origin} rel="preconnect" />
+      <link href={origin} rel="dns-prefetch" />
+    </>
+  )
+}
+
+export default MediaPreconnect