@vectoriox/iox-ui 4.33.1 → 4.34.0

package/fesm2022/vectoriox-iox-ui-seo-core.mjs

@@ -0,0 +1,368 @@
+/**
+ * The canonical shape of a page's SEO metadata, plus the flat tag list both renderers emit.
+ *
+ * ⚠️ This file is the ONLY declaration of that shape. Before it existed, `iox-cms` stored
+ * `seo.og.title` while the SSR engine read a flat `seo.ogTitle`, so no Open Graph tag had ever been
+ * emitted, and `iox-cms-client` carried a third, hand-copied variant of the same schema. See
+ * iox-ai-guidance `architecture/cms/seo-plan.md`.
+ */
+/** Recommended maximum before search results truncate the title. */
+const SEO_TITLE_MAX = 60;
+/** Recommended maximum before search results truncate the description. */
+const SEO_DESCRIPTION_MAX = 160;
+const SEO_ROBOTS_OPTIONS = [
+    { label: 'Index, Follow', value: 'index, follow' },
+    { label: 'Index, No Follow', value: 'index, nofollow' },
+    { label: 'No Index, Follow', value: 'noindex, follow' },
+    { label: 'No Index, No Follow', value: 'noindex, nofollow' },
+];
+const SEO_TWITTER_CARD_OPTIONS = [
+    { label: 'Summary', value: 'summary' },
+    { label: 'Summary Large Image', value: 'summary_large_image' },
+    { label: 'App', value: 'app' },
+    { label: 'Player', value: 'player' },
+];
+const SEO_CHANGE_FREQ_OPTIONS = [
+    { label: 'Always', value: 'always' },
+    { label: 'Hourly', value: 'hourly' },
+    { label: 'Daily', value: 'daily' },
+    { label: 'Weekly', value: 'weekly' },
+    { label: 'Monthly', value: 'monthly' },
+    { label: 'Yearly', value: 'yearly' },
+    { label: 'Never', value: 'never' },
+];
+
+/**
+ * Coerce whatever a page document happens to hold into a `SeoDoc`.
+ *
+ * Every consumer calls this before reading `seo`, because four shapes are in the wild:
+ *  • the current nested shape (`og.title`);
+ *  • the flat shape the SSR engine used to read (`ogTitle`) — never actually written, but a
+ *    document hand-edited against the old engine code could carry it;
+ *  • `""` for "not set", which must not become an empty `<meta>`;
+ *  • `{ override: '…' }`, the per-field value object that plan phase 2 introduces — tolerated here
+ *    so the ladder can land without a second normalizer.
+ *
+ * Empty branches are dropped rather than left as `{}`, so `if (seo.og)` is a meaningful test.
+ */
+function normalizeSeoDoc(raw) {
+    const src = asRecord(raw);
+    if (!src)
+        return {};
+    const og = compact({
+        title: str(pick(src, 'og', 'title') ?? src['ogTitle']),
+        description: str(pick(src, 'og', 'description') ?? src['ogDescription']),
+        image: str(pick(src, 'og', 'image') ?? src['ogImage']),
+    });
+    const twitter = compact({
+        card: str(pick(src, 'twitter', 'card')),
+        title: str(pick(src, 'twitter', 'title')),
+        description: str(pick(src, 'twitter', 'description')),
+        image: str(pick(src, 'twitter', 'image')),
+    });
+    const sitemap = compact({
+        include: bool(pick(src, 'sitemap', 'include')),
+        priority: num(pick(src, 'sitemap', 'priority')),
+        changeFreq: str(pick(src, 'sitemap', 'changeFreq')),
+    });
+    const structuredData = structured(src['structuredData']);
+    const doc = compact({
+        title: str(src['title']),
+        description: str(src['description']),
+        keywords: str(src['keywords']),
+        canonicalUrl: str(src['canonicalUrl']),
+        robots: str(src['robots']),
+        og,
+        twitter,
+        sitemap,
+        structuredData,
+    });
+    return doc ?? {};
+}
+/** Read `src[branch][leaf]` without assuming the branch exists or is an object. */
+function pick(src, branch, leaf) {
+    const nested = asRecord(src[branch]);
+    return nested ? nested[leaf] : undefined;
+}
+/**
+ * A field's value as a trimmed string, or `undefined`.
+ *
+ * Unwraps the phase-2 value object: a bound or auto field has no `override`, so it correctly
+ * resolves to `undefined` here and the binding layer fills it in later.
+ */
+function str(value) {
+    const wrapper = asRecord(value);
+    const raw = wrapper ? wrapper['override'] : value;
+    if (typeof raw === 'number')
+        return String(raw);
+    if (typeof raw !== 'string')
+        return undefined;
+    const trimmed = raw.trim();
+    return trimmed.length ? trimmed : undefined;
+}
+/**
+ * `UIFormToDTO` can hand back `"true"` / `"false"` for a switch (see
+ * `architecture/cms/shop.md` — the boolean/number coercion pitfall), so accept both.
+ */
+function bool(value) {
+    if (typeof value === 'boolean')
+        return value;
+    if (value === 'true')
+        return true;
+    if (value === 'false')
+        return false;
+    return undefined;
+}
+function num(value) {
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : undefined;
+    if (typeof value !== 'string' || !value.trim().length)
+        return undefined;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+/** JSON-LD is stored as an object or as a JSON string from the `json` controller. */
+function structured(value) {
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (!trimmed.length)
+            return undefined;
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (Array.isArray(value))
+        return value.length ? value : undefined;
+    const record = asRecord(value);
+    return record && Object.keys(record).length ? record : undefined;
+}
+function asRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/** Drop `undefined` values and empty nested objects, so absence is always `undefined`. */
+function compact(value) {
+    const out = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (entry === undefined)
+            continue;
+        out[key] = entry;
+    }
+    return (Object.keys(out).length ? out : undefined);
+}
+
+/**
+ * Turn a page's SEO document into the flat list of head tags to emit.
+ *
+ * Both renderers call this, so a page cannot describe itself differently to a crawler than the
+ * builder previews. The order is fixed and part of the contract: title, description, keywords,
+ * canonical, Open Graph, Twitter, robots.
+ *
+ * Fallbacks are deliberately shallow — `og:title` reuses the page title, `twitter:*` reuses the
+ * Open Graph values — because a social scraper that finds no `og:title` falls back to `<title>`
+ * itself, and duplicating a value we did not author only makes the drift harder to see. The
+ * "derive from the page content" half of the ladder (first h1, first paragraph, first image) is
+ * `resolveSeo`, which runs BEFORE this and hands its output in as a filled-in `SeoDoc`.
+ */
+function seoToTags(seo, ctx = {}) {
+    const doc = normalizeSeoDoc(seo);
+    const tags = [];
+    const title = doc.title ?? trimmed(ctx.fallbackTitle);
+    if (title)
+        tags.push({ kind: 'title', content: title });
+    if (doc.description)
+        tags.push({ kind: 'meta', attr: 'name', key: 'description', content: doc.description });
+    if (doc.keywords)
+        tags.push({ kind: 'meta', attr: 'name', key: 'keywords', content: doc.keywords });
+    if (doc.canonicalUrl)
+        tags.push({ kind: 'link', rel: 'canonical', href: doc.canonicalUrl });
+    // Open Graph. `og:url` reuses the canonical URL, which is what it means.
+    const ogTitle = doc.og?.title ?? title;
+    const ogDescription = doc.og?.description ?? doc.description;
+    if (ogTitle)
+        tags.push({ kind: 'meta', attr: 'property', key: 'og:title', content: ogTitle });
+    if (ogDescription)
+        tags.push({ kind: 'meta', attr: 'property', key: 'og:description', content: ogDescription });
+    if (doc.og?.image)
+        tags.push({ kind: 'meta', attr: 'property', key: 'og:image', content: doc.og.image });
+    if (doc.canonicalUrl)
+        tags.push({ kind: 'meta', attr: 'property', key: 'og:url', content: doc.canonicalUrl });
+    // Twitter. Emitted ONLY when a card type is chosen: without `twitter:card` the other tags are
+    // ignored anyway, so writing them would be noise that looks like configuration.
+    if (doc.twitter?.card) {
+        tags.push({ kind: 'meta', attr: 'name', key: 'twitter:card', content: doc.twitter.card });
+        const twitterTitle = doc.twitter.title ?? ogTitle;
+        const twitterDescription = doc.twitter.description ?? ogDescription;
+        const twitterImage = doc.twitter.image ?? doc.og?.image;
+        if (twitterTitle)
+            tags.push({ kind: 'meta', attr: 'name', key: 'twitter:title', content: twitterTitle });
+        if (twitterDescription) {
+            tags.push({ kind: 'meta', attr: 'name', key: 'twitter:description', content: twitterDescription });
+        }
+        if (twitterImage)
+            tags.push({ kind: 'meta', attr: 'name', key: 'twitter:image', content: twitterImage });
+    }
+    if (doc.robots)
+        tags.push({ kind: 'meta', attr: 'name', key: 'robots', content: doc.robots });
+    return tags;
+}
+function trimmed(value) {
+    const out = value?.trim();
+    return out?.length ? out : undefined;
+}
+
+/**
+ * The authoring schema for the `seo` object, in the platform's standard property dialect: `label`
+ * at property level, rendering metadata under `controller`.
+ *
+ * ONE builder, two callers: `iox-cms` spreads it into `PagesSchema` (the stored schema) and
+ * `iox-cms-client` feeds it to `<dynamic-form>`. Those used to be two hand-written copies that had
+ * already drifted — different controller types for the same field, and the client's copy missing
+ * `structuredData` entirely.
+ *
+ * `keywords` is deliberately absent: the tag is emitted when a document carries one, but there is
+ * no reason to invite new ones.
+ */
+function buildSeoSchemaProperties() {
+    return {
+        title: {
+            type: 'string',
+            label: 'Meta Title',
+            controller: {
+                type: 'text',
+                placeholder: 'Page title for search engines',
+                maxLength: SEO_TITLE_MAX,
+            },
+        },
+        description: {
+            type: 'string',
+            label: 'Meta Description',
+            controller: {
+                type: 'textarea',
+                placeholder: 'Brief description for search results',
+                maxLength: SEO_DESCRIPTION_MAX,
+            },
+        },
+        canonicalUrl: {
+            type: 'string',
+            label: 'Canonical URL',
+            controller: {
+                type: 'text',
+                placeholder: 'https://example.com/page',
+            },
+        },
+        robots: {
+            type: 'string',
+            label: 'Robots',
+            controller: {
+                type: 'select',
+                options: SEO_ROBOTS_OPTIONS.map(option => ({ ...option })),
+            },
+        },
+        og: {
+            type: 'object',
+            label: 'Open Graph',
+            controller: { type: 'object' },
+            properties: {
+                title: {
+                    type: 'string',
+                    label: 'OG Title',
+                    controller: { type: 'text', placeholder: 'Title for social sharing' },
+                },
+                description: {
+                    type: 'string',
+                    label: 'OG Description',
+                    controller: { type: 'textarea', placeholder: 'Description for social sharing' },
+                },
+                image: {
+                    type: 'string',
+                    label: 'OG Image',
+                    controller: { type: 'image' },
+                },
+            },
+        },
+        twitter: {
+            type: 'object',
+            label: 'Twitter Card',
+            controller: { type: 'object' },
+            properties: {
+                card: {
+                    type: 'string',
+                    label: 'Card Type',
+                    controller: {
+                        type: 'select',
+                        options: SEO_TWITTER_CARD_OPTIONS.map(option => ({ ...option })),
+                    },
+                },
+                title: {
+                    type: 'string',
+                    label: 'Twitter Title',
+                    controller: { type: 'text' },
+                },
+                description: {
+                    type: 'string',
+                    label: 'Twitter Description',
+                    controller: { type: 'textarea' },
+                },
+                image: {
+                    type: 'string',
+                    label: 'Twitter Image',
+                    controller: { type: 'image' },
+                },
+            },
+        },
+        structuredData: {
+            type: 'object',
+            label: 'Structured Data (JSON-LD)',
+            controller: { type: 'json' },
+        },
+        sitemap: {
+            type: 'object',
+            label: 'Sitemap Settings',
+            controller: { type: 'object' },
+            properties: {
+                include: {
+                    type: 'boolean',
+                    label: 'Include in Sitemap',
+                    controller: { type: 'switch' },
+                },
+                priority: {
+                    type: 'number',
+                    label: 'Priority',
+                    controller: { type: 'range', options: { min: 0, max: 1, step: 0.1 } },
+                },
+                changeFreq: {
+                    type: 'string',
+                    label: 'Change Frequency',
+                    controller: {
+                        type: 'select',
+                        options: SEO_CHANGE_FREQ_OPTIONS.map(option => ({ ...option })),
+                    },
+                },
+            },
+        },
+    };
+}
+
+/*
+ * @vectoriox/iox-ui/seo-core — the shared, FRAMEWORK-FREE core of page SEO.
+ *
+ * ⚠️ Nothing in this entry point may import Angular, RxJS, the DOM, or Node. It is consumed by
+ * THREE runtimes: the builder panel (Angular), the SSR engine (Angular), and `iox-cms` (NestJS,
+ * plain Node) — the same reason `forms-core` exists.
+ *
+ * A page describes itself to a crawler exactly once: `seoToTags` is the only place that decides
+ * which head tags a page emits, and `buildSeoSchemaProperties` the only place that declares what an
+ * author can fill in. See iox-ai-guidance `architecture/cms/seo-plan.md`.
+ */
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { SEO_CHANGE_FREQ_OPTIONS, SEO_DESCRIPTION_MAX, SEO_ROBOTS_OPTIONS, SEO_TITLE_MAX, SEO_TWITTER_CARD_OPTIONS, buildSeoSchemaProperties, normalizeSeoDoc, seoToTags };
+//# sourceMappingURL=vectoriox-iox-ui-seo-core.mjs.map

package/fesm2022/vectoriox-iox-ui-seo-core.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"vectoriox-iox-ui-seo-core.mjs","sources":["../../../projects/iox-ui/src/seo-core/seo.model.ts","../../../projects/iox-ui/src/seo-core/normalize.ts","../../../projects/iox-ui/src/seo-core/tags.ts","../../../projects/iox-ui/src/seo-core/schema.ts","../../../projects/iox-ui/src/seo-core/public-api.ts","../../../projects/iox-ui/src/seo-core/vectoriox-iox-ui-seo-core.ts"],"sourcesContent":["/**\n * The canonical shape of a page's SEO metadata, plus the flat tag list both renderers emit.\n *\n * ⚠️ This file is the ONLY declaration of that shape. Before it existed, `iox-cms` stored\n * `seo.og.title` while the SSR engine read a flat `seo.ogTitle`, so no Open Graph tag had ever been\n * emitted, and `iox-cms-client` carried a third, hand-copied variant of the same schema. See\n * iox-ai-guidance `architecture/cms/seo-plan.md`.\n */\n\n/** Open Graph subset we author and emit. */\nexport interface SeoOg {\n    title?: string;\n    description?: string;\n    image?: string;\n}\n\n/** Twitter-card subset. Emitted only when `card` is set — see `seoToTags`. */\nexport interface SeoTwitter {\n    card?: string;\n    title?: string;\n    description?: string;\n    image?: string;\n}\n\n/** Sitemap participation for this page. Consumed by the sitemap route (plan phase 3). */\nexport interface SeoSitemap {\n    include?: boolean;\n    priority?: number;\n    changeFreq?: string;\n}\n\n/**\n * A page's stored SEO metadata, normalized.\n *\n * `keywords` has no authoring field — search engines have ignored the tag for over a decade — but\n * it is read and emitted when a document already carries one, because the engine used to read it.\n */\nexport interface SeoDoc {\n    title?: string;\n    description?: string;\n    keywords?: string;\n    canonicalUrl?: string;\n    robots?: string;\n    og?: SeoOg;\n    twitter?: SeoTwitter;\n    structuredData?: unknown;\n    sitemap?: SeoSitemap;\n}\n\n/** `<title>`. */\nexport interface SeoTitleTag {\n    kind: 'title';\n    content: string;\n}\n\n/**\n * A `<meta>` tag. `attr` says which attribute identifies it — Open Graph is addressed by\n * `property`, everything else by `name`. Both renderers need that distinction to update rather\n * than duplicate a tag.\n */\nexport interface SeoMetaTag {\n    kind: 'meta';\n    attr: 'name' | 'property';\n    key: string;\n    content: string;\n}\n\n/** A `<link>`, currently only `rel=\"canonical\"`. */\nexport interface SeoLinkTag {\n    kind: 'link';\n    rel: string;\n    href: string;\n}\n\nexport type SeoTag = SeoTitleTag | SeoMetaTag | SeoLinkTag;\n\n/** Context that lets `seoToTags` fill gaps without reaching for the DOM or a data source. */\nexport interface SeoTagContext {\n    /** Used as `<title>` when the document has none — usually the page name. */\n    fallbackTitle?: string;\n}\n\n/** Recommended maximum before search results truncate the title. */\nexport const SEO_TITLE_MAX = 60;\n\n/** Recommended maximum before search results truncate the description. */\nexport const SEO_DESCRIPTION_MAX = 160;\n\nexport const SEO_ROBOTS_OPTIONS: ReadonlyArray<{ label: string; value: string }> = [\n    { label: 'Index, Follow', value: 'index, follow' },\n    { label: 'Index, No Follow', value: 'index, nofollow' },\n    { label: 'No Index, Follow', value: 'noindex, follow' },\n    { label: 'No Index, No Follow', value: 'noindex, nofollow' },\n];\n\nexport const SEO_TWITTER_CARD_OPTIONS: ReadonlyArray<{ label: string; value: string }> = [\n    { label: 'Summary', value: 'summary' },\n    { label: 'Summary Large Image', value: 'summary_large_image' },\n    { label: 'App', value: 'app' },\n    { label: 'Player', value: 'player' },\n];\n\nexport const SEO_CHANGE_FREQ_OPTIONS: ReadonlyArray<{ label: string; value: string }> = [\n    { label: 'Always', value: 'always' },\n    { label: 'Hourly', value: 'hourly' },\n    { label: 'Daily', value: 'daily' },\n    { label: 'Weekly', value: 'weekly' },\n    { label: 'Monthly', value: 'monthly' },\n    { label: 'Yearly', value: 'yearly' },\n    { label: 'Never', value: 'never' },\n];\n","import { SeoDoc, SeoOg, SeoSitemap, SeoTwitter } from './seo.model';\n\n/**\n * Coerce whatever a page document happens to hold into a `SeoDoc`.\n *\n * Every consumer calls this before reading `seo`, because four shapes are in the wild:\n *  • the current nested shape (`og.title`);\n *  • the flat shape the SSR engine used to read (`ogTitle`) — never actually written, but a\n *    document hand-edited against the old engine code could carry it;\n *  • `\"\"` for \"not set\", which must not become an empty `<meta>`;\n *  • `{ override: '…' }`, the per-field value object that plan phase 2 introduces — tolerated here\n *    so the ladder can land without a second normalizer.\n *\n * Empty branches are dropped rather than left as `{}`, so `if (seo.og)` is a meaningful test.\n */\nexport function normalizeSeoDoc(raw: unknown): SeoDoc {\n    const src = asRecord(raw);\n    if (!src) return {};\n\n    const og = compact<SeoOg>({\n        title: str(pick(src, 'og', 'title') ?? src['ogTitle']),\n        description: str(pick(src, 'og', 'description') ?? src['ogDescription']),\n        image: str(pick(src, 'og', 'image') ?? src['ogImage']),\n    });\n\n    const twitter = compact<SeoTwitter>({\n        card: str(pick(src, 'twitter', 'card')),\n        title: str(pick(src, 'twitter', 'title')),\n        description: str(pick(src, 'twitter', 'description')),\n        image: str(pick(src, 'twitter', 'image')),\n    });\n\n    const sitemap = compact<SeoSitemap>({\n        include: bool(pick(src, 'sitemap', 'include')),\n        priority: num(pick(src, 'sitemap', 'priority')),\n        changeFreq: str(pick(src, 'sitemap', 'changeFreq')),\n    });\n\n    const structuredData = structured(src['structuredData']);\n\n    const doc = compact<SeoDoc>({\n        title: str(src['title']),\n        description: str(src['description']),\n        keywords: str(src['keywords']),\n        canonicalUrl: str(src['canonicalUrl']),\n        robots: str(src['robots']),\n        og,\n        twitter,\n        sitemap,\n        structuredData,\n    });\n\n    return doc ?? {};\n}\n\n/** Read `src[branch][leaf]` without assuming the branch exists or is an object. */\nfunction pick(src: Record<string, unknown>, branch: string, leaf: string): unknown {\n    const nested = asRecord(src[branch]);\n    return nested ? nested[leaf] : undefined;\n}\n\n/**\n * A field's value as a trimmed string, or `undefined`.\n *\n * Unwraps the phase-2 value object: a bound or auto field has no `override`, so it correctly\n * resolves to `undefined` here and the binding layer fills it in later.\n */\nfunction str(value: unknown): string | undefined {\n    const wrapper = asRecord(value);\n    const raw = wrapper ? wrapper['override'] : value;\n    if (typeof raw === 'number') return String(raw);\n    if (typeof raw !== 'string') return undefined;\n    const trimmed = raw.trim();\n    return trimmed.length ? trimmed : undefined;\n}\n\n/**\n * `UIFormToDTO` can hand back `\"true\"` / `\"false\"` for a switch (see\n * `architecture/cms/shop.md` — the boolean/number coercion pitfall), so accept both.\n */\nfunction bool(value: unknown): boolean | undefined {\n    if (typeof value === 'boolean') return value;\n    if (value === 'true') return true;\n    if (value === 'false') return false;\n    return undefined;\n}\n\nfunction num(value: unknown): number | undefined {\n    if (typeof value === 'number') return Number.isFinite(value) ? value : undefined;\n    if (typeof value !== 'string' || !value.trim().length) return undefined;\n    const parsed = Number(value);\n    return Number.isFinite(parsed) ? parsed : undefined;\n}\n\n/** JSON-LD is stored as an object or as a JSON string from the `json` controller. */\nfunction structured(value: unknown): unknown {\n    if (typeof value === 'string') {\n        const trimmed = value.trim();\n        if (!trimmed.length) return undefined;\n        try {\n            return JSON.parse(trimmed);\n        } catch {\n            return undefined;\n        }\n    }\n    if (Array.isArray(value)) return value.length ? value : undefined;\n    const record = asRecord(value);\n    return record && Object.keys(record).length ? record : undefined;\n}\n\nfunction asRecord(value: unknown): Record<string, unknown> | undefined {\n    return value !== null && typeof value === 'object' && !Array.isArray(value)\n        ? (value as Record<string, unknown>)\n        : undefined;\n}\n\n/** Drop `undefined` values and empty nested objects, so absence is always `undefined`. */\nfunction compact<T extends object>(value: Record<string, unknown>): T | undefined {\n    const out: Record<string, unknown> = {};\n    for (const [key, entry] of Object.entries(value)) {\n        if (entry === undefined) continue;\n        out[key] = entry;\n    }\n    return (Object.keys(out).length ? out : undefined) as T | undefined;\n}\n","import { SeoDoc, SeoTag, SeoTagContext } from './seo.model';\nimport { normalizeSeoDoc } from './normalize';\n\n/**\n * Turn a page's SEO document into the flat list of head tags to emit.\n *\n * Both renderers call this, so a page cannot describe itself differently to a crawler than the\n * builder previews. The order is fixed and part of the contract: title, description, keywords,\n * canonical, Open Graph, Twitter, robots.\n *\n * Fallbacks are deliberately shallow — `og:title` reuses the page title, `twitter:*` reuses the\n * Open Graph values — because a social scraper that finds no `og:title` falls back to `<title>`\n * itself, and duplicating a value we did not author only makes the drift harder to see. The\n * \"derive from the page content\" half of the ladder (first h1, first paragraph, first image) is\n * `resolveSeo`, which runs BEFORE this and hands its output in as a filled-in `SeoDoc`.\n */\nexport function seoToTags(seo: SeoDoc | unknown, ctx: SeoTagContext = {}): SeoTag[] {\n    const doc = normalizeSeoDoc(seo);\n    const tags: SeoTag[] = [];\n\n    const title = doc.title ?? trimmed(ctx.fallbackTitle);\n    if (title) tags.push({ kind: 'title', content: title });\n    if (doc.description) tags.push({ kind: 'meta', attr: 'name', key: 'description', content: doc.description });\n    if (doc.keywords) tags.push({ kind: 'meta', attr: 'name', key: 'keywords', content: doc.keywords });\n    if (doc.canonicalUrl) tags.push({ kind: 'link', rel: 'canonical', href: doc.canonicalUrl });\n\n    // Open Graph. `og:url` reuses the canonical URL, which is what it means.\n    const ogTitle = doc.og?.title ?? title;\n    const ogDescription = doc.og?.description ?? doc.description;\n    if (ogTitle) tags.push({ kind: 'meta', attr: 'property', key: 'og:title', content: ogTitle });\n    if (ogDescription) tags.push({ kind: 'meta', attr: 'property', key: 'og:description', content: ogDescription });\n    if (doc.og?.image) tags.push({ kind: 'meta', attr: 'property', key: 'og:image', content: doc.og.image });\n    if (doc.canonicalUrl) tags.push({ kind: 'meta', attr: 'property', key: 'og:url', content: doc.canonicalUrl });\n\n    // Twitter. Emitted ONLY when a card type is chosen: without `twitter:card` the other tags are\n    // ignored anyway, so writing them would be noise that looks like configuration.\n    if (doc.twitter?.card) {\n        tags.push({ kind: 'meta', attr: 'name', key: 'twitter:card', content: doc.twitter.card });\n        const twitterTitle = doc.twitter.title ?? ogTitle;\n        const twitterDescription = doc.twitter.description ?? ogDescription;\n        const twitterImage = doc.twitter.image ?? doc.og?.image;\n        if (twitterTitle) tags.push({ kind: 'meta', attr: 'name', key: 'twitter:title', content: twitterTitle });\n        if (twitterDescription) {\n            tags.push({ kind: 'meta', attr: 'name', key: 'twitter:description', content: twitterDescription });\n        }\n        if (twitterImage) tags.push({ kind: 'meta', attr: 'name', key: 'twitter:image', content: twitterImage });\n    }\n\n    if (doc.robots) tags.push({ kind: 'meta', attr: 'name', key: 'robots', content: doc.robots });\n\n    return tags;\n}\n\nfunction trimmed(value: string | undefined): string | undefined {\n    const out = value?.trim();\n    return out?.length ? out : undefined;\n}\n","import {\n    SEO_CHANGE_FREQ_OPTIONS,\n    SEO_DESCRIPTION_MAX,\n    SEO_ROBOTS_OPTIONS,\n    SEO_TITLE_MAX,\n    SEO_TWITTER_CARD_OPTIONS,\n} from './seo.model';\n\n/**\n * The authoring schema for the `seo` object, in the platform's standard property dialect: `label`\n * at property level, rendering metadata under `controller`.\n *\n * ONE builder, two callers: `iox-cms` spreads it into `PagesSchema` (the stored schema) and\n * `iox-cms-client` feeds it to `<dynamic-form>`. Those used to be two hand-written copies that had\n * already drifted — different controller types for the same field, and the client's copy missing\n * `structuredData` entirely.\n *\n * `keywords` is deliberately absent: the tag is emitted when a document carries one, but there is\n * no reason to invite new ones.\n */\nexport function buildSeoSchemaProperties(): Record<string, unknown> {\n    return {\n        title: {\n            type: 'string',\n            label: 'Meta Title',\n            controller: {\n                type: 'text',\n                placeholder: 'Page title for search engines',\n                maxLength: SEO_TITLE_MAX,\n            },\n        },\n        description: {\n            type: 'string',\n            label: 'Meta Description',\n            controller: {\n                type: 'textarea',\n                placeholder: 'Brief description for search results',\n                maxLength: SEO_DESCRIPTION_MAX,\n            },\n        },\n        canonicalUrl: {\n            type: 'string',\n            label: 'Canonical URL',\n            controller: {\n                type: 'text',\n                placeholder: 'https://example.com/page',\n            },\n        },\n        robots: {\n            type: 'string',\n            label: 'Robots',\n            controller: {\n                type: 'select',\n                options: SEO_ROBOTS_OPTIONS.map(option => ({ ...option })),\n            },\n        },\n        og: {\n            type: 'object',\n            label: 'Open Graph',\n            controller: { type: 'object' },\n            properties: {\n                title: {\n                    type: 'string',\n                    label: 'OG Title',\n                    controller: { type: 'text', placeholder: 'Title for social sharing' },\n                },\n                description: {\n                    type: 'string',\n                    label: 'OG Description',\n                    controller: { type: 'textarea', placeholder: 'Description for social sharing' },\n                },\n                image: {\n                    type: 'string',\n                    label: 'OG Image',\n                    controller: { type: 'image' },\n                },\n            },\n        },\n        twitter: {\n            type: 'object',\n            label: 'Twitter Card',\n            controller: { type: 'object' },\n            properties: {\n                card: {\n                    type: 'string',\n                    label: 'Card Type',\n                    controller: {\n                        type: 'select',\n                        options: SEO_TWITTER_CARD_OPTIONS.map(option => ({ ...option })),\n                    },\n                },\n                title: {\n                    type: 'string',\n                    label: 'Twitter Title',\n                    controller: { type: 'text' },\n                },\n                description: {\n                    type: 'string',\n                    label: 'Twitter Description',\n                    controller: { type: 'textarea' },\n                },\n                image: {\n                    type: 'string',\n                    label: 'Twitter Image',\n                    controller: { type: 'image' },\n                },\n            },\n        },\n        structuredData: {\n            type: 'object',\n            label: 'Structured Data (JSON-LD)',\n            controller: { type: 'json' },\n        },\n        sitemap: {\n            type: 'object',\n            label: 'Sitemap Settings',\n            controller: { type: 'object' },\n            properties: {\n                include: {\n                    type: 'boolean',\n                    label: 'Include in Sitemap',\n                    controller: { type: 'switch' },\n                },\n                priority: {\n                    type: 'number',\n                    label: 'Priority',\n                    controller: { type: 'range', options: { min: 0, max: 1, step: 0.1 } },\n                },\n                changeFreq: {\n                    type: 'string',\n                    label: 'Change Frequency',\n                    controller: {\n                        type: 'select',\n                        options: SEO_CHANGE_FREQ_OPTIONS.map(option => ({ ...option })),\n                    },\n                },\n            },\n        },\n    };\n}\n","/*\n * @vectoriox/iox-ui/seo-core — the shared, FRAMEWORK-FREE core of page SEO.\n *\n * ⚠️ Nothing in this entry point may import Angular, RxJS, the DOM, or Node. It is consumed by\n * THREE runtimes: the builder panel (Angular), the SSR engine (Angular), and `iox-cms` (NestJS,\n * plain Node) — the same reason `forms-core` exists.\n *\n * A page describes itself to a crawler exactly once: `seoToTags` is the only place that decides\n * which head tags a page emits, and `buildSeoSchemaProperties` the only place that declares what an\n * author can fill in. See iox-ai-guidance `architecture/cms/seo-plan.md`.\n */\n\nexport * from './seo.model';\nexport * from './normalize';\nexport * from './tags';\nexport * from './schema';\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './public-api';\n"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "4.33.1",
+  "version": "4.34.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",
@@ -22,6 +22,10 @@
     "./forms-core": {
       "types": "./forms-core/index.d.ts",
       "default": "./fesm2022/vectoriox-iox-ui-forms-core.mjs"
+    },
+    "./seo-core": {
+      "types": "./seo-core/index.d.ts",
+      "default": "./fesm2022/vectoriox-iox-ui-seo-core.mjs"
     }
   },
   "sideEffects": false

package/seo-core/index.d.ts

@@ -0,0 +1,135 @@
+/**
+ * The canonical shape of a page's SEO metadata, plus the flat tag list both renderers emit.
+ *
+ * ⚠️ This file is the ONLY declaration of that shape. Before it existed, `iox-cms` stored
+ * `seo.og.title` while the SSR engine read a flat `seo.ogTitle`, so no Open Graph tag had ever been
+ * emitted, and `iox-cms-client` carried a third, hand-copied variant of the same schema. See
+ * iox-ai-guidance `architecture/cms/seo-plan.md`.
+ */
+/** Open Graph subset we author and emit. */
+interface SeoOg {
+    title?: string;
+    description?: string;
+    image?: string;
+}
+/** Twitter-card subset. Emitted only when `card` is set — see `seoToTags`. */
+interface SeoTwitter {
+    card?: string;
+    title?: string;
+    description?: string;
+    image?: string;
+}
+/** Sitemap participation for this page. Consumed by the sitemap route (plan phase 3). */
+interface SeoSitemap {
+    include?: boolean;
+    priority?: number;
+    changeFreq?: string;
+}
+/**
+ * A page's stored SEO metadata, normalized.
+ *
+ * `keywords` has no authoring field — search engines have ignored the tag for over a decade — but
+ * it is read and emitted when a document already carries one, because the engine used to read it.
+ */
+interface SeoDoc {
+    title?: string;
+    description?: string;
+    keywords?: string;
+    canonicalUrl?: string;
+    robots?: string;
+    og?: SeoOg;
+    twitter?: SeoTwitter;
+    structuredData?: unknown;
+    sitemap?: SeoSitemap;
+}
+/** `<title>`. */
+interface SeoTitleTag {
+    kind: 'title';
+    content: string;
+}
+/**
+ * A `<meta>` tag. `attr` says which attribute identifies it — Open Graph is addressed by
+ * `property`, everything else by `name`. Both renderers need that distinction to update rather
+ * than duplicate a tag.
+ */
+interface SeoMetaTag {
+    kind: 'meta';
+    attr: 'name' | 'property';
+    key: string;
+    content: string;
+}
+/** A `<link>`, currently only `rel="canonical"`. */
+interface SeoLinkTag {
+    kind: 'link';
+    rel: string;
+    href: string;
+}
+type SeoTag = SeoTitleTag | SeoMetaTag | SeoLinkTag;
+/** Context that lets `seoToTags` fill gaps without reaching for the DOM or a data source. */
+interface SeoTagContext {
+    /** Used as `<title>` when the document has none — usually the page name. */
+    fallbackTitle?: string;
+}
+/** Recommended maximum before search results truncate the title. */
+declare const SEO_TITLE_MAX = 60;
+/** Recommended maximum before search results truncate the description. */
+declare const SEO_DESCRIPTION_MAX = 160;
+declare const SEO_ROBOTS_OPTIONS: ReadonlyArray<{
+    label: string;
+    value: string;
+}>;
+declare const SEO_TWITTER_CARD_OPTIONS: ReadonlyArray<{
+    label: string;
+    value: string;
+}>;
+declare const SEO_CHANGE_FREQ_OPTIONS: ReadonlyArray<{
+    label: string;
+    value: string;
+}>;
+
+/**
+ * Coerce whatever a page document happens to hold into a `SeoDoc`.
+ *
+ * Every consumer calls this before reading `seo`, because four shapes are in the wild:
+ *  • the current nested shape (`og.title`);
+ *  • the flat shape the SSR engine used to read (`ogTitle`) — never actually written, but a
+ *    document hand-edited against the old engine code could carry it;
+ *  • `""` for "not set", which must not become an empty `<meta>`;
+ *  • `{ override: '…' }`, the per-field value object that plan phase 2 introduces — tolerated here
+ *    so the ladder can land without a second normalizer.
+ *
+ * Empty branches are dropped rather than left as `{}`, so `if (seo.og)` is a meaningful test.
+ */
+declare function normalizeSeoDoc(raw: unknown): SeoDoc;
+
+/**
+ * Turn a page's SEO document into the flat list of head tags to emit.
+ *
+ * Both renderers call this, so a page cannot describe itself differently to a crawler than the
+ * builder previews. The order is fixed and part of the contract: title, description, keywords,
+ * canonical, Open Graph, Twitter, robots.
+ *
+ * Fallbacks are deliberately shallow — `og:title` reuses the page title, `twitter:*` reuses the
+ * Open Graph values — because a social scraper that finds no `og:title` falls back to `<title>`
+ * itself, and duplicating a value we did not author only makes the drift harder to see. The
+ * "derive from the page content" half of the ladder (first h1, first paragraph, first image) is
+ * `resolveSeo`, which runs BEFORE this and hands its output in as a filled-in `SeoDoc`.
+ */
+declare function seoToTags(seo: SeoDoc | unknown, ctx?: SeoTagContext): SeoTag[];
+
+/**
+ * The authoring schema for the `seo` object, in the platform's standard property dialect: `label`
+ * at property level, rendering metadata under `controller`.
+ *
+ * ONE builder, two callers: `iox-cms` spreads it into `PagesSchema` (the stored schema) and
+ * `iox-cms-client` feeds it to `<dynamic-form>`. Those used to be two hand-written copies that had
+ * already drifted — different controller types for the same field, and the client's copy missing
+ * `structuredData` entirely.
+ *
+ * `keywords` is deliberately absent: the tag is emitted when a document carries one, but there is
+ * no reason to invite new ones.
+ */
+declare function buildSeoSchemaProperties(): Record<string, unknown>;
+
+export { SEO_CHANGE_FREQ_OPTIONS, SEO_DESCRIPTION_MAX, SEO_ROBOTS_OPTIONS, SEO_TITLE_MAX, SEO_TWITTER_CARD_OPTIONS, buildSeoSchemaProperties, normalizeSeoDoc, seoToTags };
+export type { SeoDoc, SeoLinkTag, SeoMetaTag, SeoOg, SeoSitemap, SeoTag, SeoTagContext, SeoTitleTag, SeoTwitter };

package/seo-core/package.json

@@ -0,0 +1,3 @@
+{
+  "module": "../fesm2022/vectoriox-iox-ui-seo-core.mjs"
+}

package/src/seo-core/normalize.ts

@@ -0,0 +1,125 @@
+import { SeoDoc, SeoOg, SeoSitemap, SeoTwitter } from './seo.model';
+
+/**
+ * Coerce whatever a page document happens to hold into a `SeoDoc`.
+ *
+ * Every consumer calls this before reading `seo`, because four shapes are in the wild:
+ *  • the current nested shape (`og.title`);
+ *  • the flat shape the SSR engine used to read (`ogTitle`) — never actually written, but a
+ *    document hand-edited against the old engine code could carry it;
+ *  • `""` for "not set", which must not become an empty `<meta>`;
+ *  • `{ override: '…' }`, the per-field value object that plan phase 2 introduces — tolerated here
+ *    so the ladder can land without a second normalizer.
+ *
+ * Empty branches are dropped rather than left as `{}`, so `if (seo.og)` is a meaningful test.
+ */
+export function normalizeSeoDoc(raw: unknown): SeoDoc {
+    const src = asRecord(raw);
+    if (!src) return {};
+
+    const og = compact<SeoOg>({
+        title: str(pick(src, 'og', 'title') ?? src['ogTitle']),
+        description: str(pick(src, 'og', 'description') ?? src['ogDescription']),
+        image: str(pick(src, 'og', 'image') ?? src['ogImage']),
+    });
+
+    const twitter = compact<SeoTwitter>({
+        card: str(pick(src, 'twitter', 'card')),
+        title: str(pick(src, 'twitter', 'title')),
+        description: str(pick(src, 'twitter', 'description')),
+        image: str(pick(src, 'twitter', 'image')),
+    });
+
+    const sitemap = compact<SeoSitemap>({
+        include: bool(pick(src, 'sitemap', 'include')),
+        priority: num(pick(src, 'sitemap', 'priority')),
+        changeFreq: str(pick(src, 'sitemap', 'changeFreq')),
+    });
+
+    const structuredData = structured(src['structuredData']);
+
+    const doc = compact<SeoDoc>({
+        title: str(src['title']),
+        description: str(src['description']),
+        keywords: str(src['keywords']),
+        canonicalUrl: str(src['canonicalUrl']),
+        robots: str(src['robots']),
+        og,
+        twitter,
+        sitemap,
+        structuredData,
+    });
+
+    return doc ?? {};
+}
+
+/** Read `src[branch][leaf]` without assuming the branch exists or is an object. */
+function pick(src: Record<string, unknown>, branch: string, leaf: string): unknown {
+    const nested = asRecord(src[branch]);
+    return nested ? nested[leaf] : undefined;
+}
+
+/**
+ * A field's value as a trimmed string, or `undefined`.
+ *
+ * Unwraps the phase-2 value object: a bound or auto field has no `override`, so it correctly
+ * resolves to `undefined` here and the binding layer fills it in later.
+ */
+function str(value: unknown): string | undefined {
+    const wrapper = asRecord(value);
+    const raw = wrapper ? wrapper['override'] : value;
+    if (typeof raw === 'number') return String(raw);
+    if (typeof raw !== 'string') return undefined;
+    const trimmed = raw.trim();
+    return trimmed.length ? trimmed : undefined;
+}
+
+/**
+ * `UIFormToDTO` can hand back `"true"` / `"false"` for a switch (see
+ * `architecture/cms/shop.md` — the boolean/number coercion pitfall), so accept both.
+ */
+function bool(value: unknown): boolean | undefined {
+    if (typeof value === 'boolean') return value;
+    if (value === 'true') return true;
+    if (value === 'false') return false;
+    return undefined;
+}
+
+function num(value: unknown): number | undefined {
+    if (typeof value === 'number') return Number.isFinite(value) ? value : undefined;
+    if (typeof value !== 'string' || !value.trim().length) return undefined;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+/** JSON-LD is stored as an object or as a JSON string from the `json` controller. */
+function structured(value: unknown): unknown {
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (!trimmed.length) return undefined;
+        try {
+            return JSON.parse(trimmed);
+        } catch {
+            return undefined;
+        }
+    }
+    if (Array.isArray(value)) return value.length ? value : undefined;
+    const record = asRecord(value);
+    return record && Object.keys(record).length ? record : undefined;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? (value as Record<string, unknown>)
+        : undefined;
+}
+
+/** Drop `undefined` values and empty nested objects, so absence is always `undefined`. */
+function compact<T extends object>(value: Record<string, unknown>): T | undefined {
+    const out: Record<string, unknown> = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (entry === undefined) continue;
+        out[key] = entry;
+    }
+    return (Object.keys(out).length ? out : undefined) as T | undefined;
+}

package/src/seo-core/public-api.ts

@@ -0,0 +1,16 @@
+/*
+ * @vectoriox/iox-ui/seo-core — the shared, FRAMEWORK-FREE core of page SEO.
+ *
+ * ⚠️ Nothing in this entry point may import Angular, RxJS, the DOM, or Node. It is consumed by
+ * THREE runtimes: the builder panel (Angular), the SSR engine (Angular), and `iox-cms` (NestJS,
+ * plain Node) — the same reason `forms-core` exists.
+ *
+ * A page describes itself to a crawler exactly once: `seoToTags` is the only place that decides
+ * which head tags a page emits, and `buildSeoSchemaProperties` the only place that declares what an
+ * author can fill in. See iox-ai-guidance `architecture/cms/seo-plan.md`.
+ */
+
+export * from './seo.model';
+export * from './normalize';
+export * from './tags';
+export * from './schema';

package/src/seo-core/schema.ts

@@ -0,0 +1,140 @@
+import {
+    SEO_CHANGE_FREQ_OPTIONS,
+    SEO_DESCRIPTION_MAX,
+    SEO_ROBOTS_OPTIONS,
+    SEO_TITLE_MAX,
+    SEO_TWITTER_CARD_OPTIONS,
+} from './seo.model';
+
+/**
+ * The authoring schema for the `seo` object, in the platform's standard property dialect: `label`
+ * at property level, rendering metadata under `controller`.
+ *
+ * ONE builder, two callers: `iox-cms` spreads it into `PagesSchema` (the stored schema) and
+ * `iox-cms-client` feeds it to `<dynamic-form>`. Those used to be two hand-written copies that had
+ * already drifted — different controller types for the same field, and the client's copy missing
+ * `structuredData` entirely.
+ *
+ * `keywords` is deliberately absent: the tag is emitted when a document carries one, but there is
+ * no reason to invite new ones.
+ */
+export function buildSeoSchemaProperties(): Record<string, unknown> {
+    return {
+        title: {
+            type: 'string',
+            label: 'Meta Title',
+            controller: {
+                type: 'text',
+                placeholder: 'Page title for search engines',
+                maxLength: SEO_TITLE_MAX,
+            },
+        },
+        description: {
+            type: 'string',
+            label: 'Meta Description',
+            controller: {
+                type: 'textarea',
+                placeholder: 'Brief description for search results',
+                maxLength: SEO_DESCRIPTION_MAX,
+            },
+        },
+        canonicalUrl: {
+            type: 'string',
+            label: 'Canonical URL',
+            controller: {
+                type: 'text',
+                placeholder: 'https://example.com/page',
+            },
+        },
+        robots: {
+            type: 'string',
+            label: 'Robots',
+            controller: {
+                type: 'select',
+                options: SEO_ROBOTS_OPTIONS.map(option => ({ ...option })),
+            },
+        },
+        og: {
+            type: 'object',
+            label: 'Open Graph',
+            controller: { type: 'object' },
+            properties: {
+                title: {
+                    type: 'string',
+                    label: 'OG Title',
+                    controller: { type: 'text', placeholder: 'Title for social sharing' },
+                },
+                description: {
+                    type: 'string',
+                    label: 'OG Description',
+                    controller: { type: 'textarea', placeholder: 'Description for social sharing' },
+                },
+                image: {
+                    type: 'string',
+                    label: 'OG Image',
+                    controller: { type: 'image' },
+                },
+            },
+        },
+        twitter: {
+            type: 'object',
+            label: 'Twitter Card',
+            controller: { type: 'object' },
+            properties: {
+                card: {
+                    type: 'string',
+                    label: 'Card Type',
+                    controller: {
+                        type: 'select',
+                        options: SEO_TWITTER_CARD_OPTIONS.map(option => ({ ...option })),
+                    },
+                },
+                title: {
+                    type: 'string',
+                    label: 'Twitter Title',
+                    controller: { type: 'text' },
+                },
+                description: {
+                    type: 'string',
+                    label: 'Twitter Description',
+                    controller: { type: 'textarea' },
+                },
+                image: {
+                    type: 'string',
+                    label: 'Twitter Image',
+                    controller: { type: 'image' },
+                },
+            },
+        },
+        structuredData: {
+            type: 'object',
+            label: 'Structured Data (JSON-LD)',
+            controller: { type: 'json' },
+        },
+        sitemap: {
+            type: 'object',
+            label: 'Sitemap Settings',
+            controller: { type: 'object' },
+            properties: {
+                include: {
+                    type: 'boolean',
+                    label: 'Include in Sitemap',
+                    controller: { type: 'switch' },
+                },
+                priority: {
+                    type: 'number',
+                    label: 'Priority',
+                    controller: { type: 'range', options: { min: 0, max: 1, step: 0.1 } },
+                },
+                changeFreq: {
+                    type: 'string',
+                    label: 'Change Frequency',
+                    controller: {
+                        type: 'select',
+                        options: SEO_CHANGE_FREQ_OPTIONS.map(option => ({ ...option })),
+                    },
+                },
+            },
+        },
+    };
+}

package/src/seo-core/seo.model.ts

@@ -0,0 +1,111 @@
+/**
+ * The canonical shape of a page's SEO metadata, plus the flat tag list both renderers emit.
+ *
+ * ⚠️ This file is the ONLY declaration of that shape. Before it existed, `iox-cms` stored
+ * `seo.og.title` while the SSR engine read a flat `seo.ogTitle`, so no Open Graph tag had ever been
+ * emitted, and `iox-cms-client` carried a third, hand-copied variant of the same schema. See
+ * iox-ai-guidance `architecture/cms/seo-plan.md`.
+ */
+
+/** Open Graph subset we author and emit. */
+export interface SeoOg {
+    title?: string;
+    description?: string;
+    image?: string;
+}
+
+/** Twitter-card subset. Emitted only when `card` is set — see `seoToTags`. */
+export interface SeoTwitter {
+    card?: string;
+    title?: string;
+    description?: string;
+    image?: string;
+}
+
+/** Sitemap participation for this page. Consumed by the sitemap route (plan phase 3). */
+export interface SeoSitemap {
+    include?: boolean;
+    priority?: number;
+    changeFreq?: string;
+}
+
+/**
+ * A page's stored SEO metadata, normalized.
+ *
+ * `keywords` has no authoring field — search engines have ignored the tag for over a decade — but
+ * it is read and emitted when a document already carries one, because the engine used to read it.
+ */
+export interface SeoDoc {
+    title?: string;
+    description?: string;
+    keywords?: string;
+    canonicalUrl?: string;
+    robots?: string;
+    og?: SeoOg;
+    twitter?: SeoTwitter;
+    structuredData?: unknown;
+    sitemap?: SeoSitemap;
+}
+
+/** `<title>`. */
+export interface SeoTitleTag {
+    kind: 'title';
+    content: string;
+}
+
+/**
+ * A `<meta>` tag. `attr` says which attribute identifies it — Open Graph is addressed by
+ * `property`, everything else by `name`. Both renderers need that distinction to update rather
+ * than duplicate a tag.
+ */
+export interface SeoMetaTag {
+    kind: 'meta';
+    attr: 'name' | 'property';
+    key: string;
+    content: string;
+}
+
+/** A `<link>`, currently only `rel="canonical"`. */
+export interface SeoLinkTag {
+    kind: 'link';
+    rel: string;
+    href: string;
+}
+
+export type SeoTag = SeoTitleTag | SeoMetaTag | SeoLinkTag;
+
+/** Context that lets `seoToTags` fill gaps without reaching for the DOM or a data source. */
+export interface SeoTagContext {
+    /** Used as `<title>` when the document has none — usually the page name. */
+    fallbackTitle?: string;
+}
+
+/** Recommended maximum before search results truncate the title. */
+export const SEO_TITLE_MAX = 60;
+
+/** Recommended maximum before search results truncate the description. */
+export const SEO_DESCRIPTION_MAX = 160;
+
+export const SEO_ROBOTS_OPTIONS: ReadonlyArray<{ label: string; value: string }> = [
+    { label: 'Index, Follow', value: 'index, follow' },
+    { label: 'Index, No Follow', value: 'index, nofollow' },
+    { label: 'No Index, Follow', value: 'noindex, follow' },
+    { label: 'No Index, No Follow', value: 'noindex, nofollow' },
+];
+
+export const SEO_TWITTER_CARD_OPTIONS: ReadonlyArray<{ label: string; value: string }> = [
+    { label: 'Summary', value: 'summary' },
+    { label: 'Summary Large Image', value: 'summary_large_image' },
+    { label: 'App', value: 'app' },
+    { label: 'Player', value: 'player' },
+];
+
+export const SEO_CHANGE_FREQ_OPTIONS: ReadonlyArray<{ label: string; value: string }> = [
+    { label: 'Always', value: 'always' },
+    { label: 'Hourly', value: 'hourly' },
+    { label: 'Daily', value: 'daily' },
+    { label: 'Weekly', value: 'weekly' },
+    { label: 'Monthly', value: 'monthly' },
+    { label: 'Yearly', value: 'yearly' },
+    { label: 'Never', value: 'never' },
+];

package/src/seo-core/tags.ts

@@ -0,0 +1,57 @@
+import { SeoDoc, SeoTag, SeoTagContext } from './seo.model';
+import { normalizeSeoDoc } from './normalize';
+
+/**
+ * Turn a page's SEO document into the flat list of head tags to emit.
+ *
+ * Both renderers call this, so a page cannot describe itself differently to a crawler than the
+ * builder previews. The order is fixed and part of the contract: title, description, keywords,
+ * canonical, Open Graph, Twitter, robots.
+ *
+ * Fallbacks are deliberately shallow — `og:title` reuses the page title, `twitter:*` reuses the
+ * Open Graph values — because a social scraper that finds no `og:title` falls back to `<title>`
+ * itself, and duplicating a value we did not author only makes the drift harder to see. The
+ * "derive from the page content" half of the ladder (first h1, first paragraph, first image) is
+ * `resolveSeo`, which runs BEFORE this and hands its output in as a filled-in `SeoDoc`.
+ */
+export function seoToTags(seo: SeoDoc | unknown, ctx: SeoTagContext = {}): SeoTag[] {
+    const doc = normalizeSeoDoc(seo);
+    const tags: SeoTag[] = [];
+
+    const title = doc.title ?? trimmed(ctx.fallbackTitle);
+    if (title) tags.push({ kind: 'title', content: title });
+    if (doc.description) tags.push({ kind: 'meta', attr: 'name', key: 'description', content: doc.description });
+    if (doc.keywords) tags.push({ kind: 'meta', attr: 'name', key: 'keywords', content: doc.keywords });
+    if (doc.canonicalUrl) tags.push({ kind: 'link', rel: 'canonical', href: doc.canonicalUrl });
+
+    // Open Graph. `og:url` reuses the canonical URL, which is what it means.
+    const ogTitle = doc.og?.title ?? title;
+    const ogDescription = doc.og?.description ?? doc.description;
+    if (ogTitle) tags.push({ kind: 'meta', attr: 'property', key: 'og:title', content: ogTitle });
+    if (ogDescription) tags.push({ kind: 'meta', attr: 'property', key: 'og:description', content: ogDescription });
+    if (doc.og?.image) tags.push({ kind: 'meta', attr: 'property', key: 'og:image', content: doc.og.image });
+    if (doc.canonicalUrl) tags.push({ kind: 'meta', attr: 'property', key: 'og:url', content: doc.canonicalUrl });
+
+    // Twitter. Emitted ONLY when a card type is chosen: without `twitter:card` the other tags are
+    // ignored anyway, so writing them would be noise that looks like configuration.
+    if (doc.twitter?.card) {
+        tags.push({ kind: 'meta', attr: 'name', key: 'twitter:card', content: doc.twitter.card });
+        const twitterTitle = doc.twitter.title ?? ogTitle;
+        const twitterDescription = doc.twitter.description ?? ogDescription;
+        const twitterImage = doc.twitter.image ?? doc.og?.image;
+        if (twitterTitle) tags.push({ kind: 'meta', attr: 'name', key: 'twitter:title', content: twitterTitle });
+        if (twitterDescription) {
+            tags.push({ kind: 'meta', attr: 'name', key: 'twitter:description', content: twitterDescription });
+        }
+        if (twitterImage) tags.push({ kind: 'meta', attr: 'name', key: 'twitter:image', content: twitterImage });
+    }
+
+    if (doc.robots) tags.push({ kind: 'meta', attr: 'name', key: 'robots', content: doc.robots });
+
+    return tags;
+}
+
+function trimmed(value: string | undefined): string | undefined {
+    const out = value?.trim();
+    return out?.length ? out : undefined;
+}