@krantho/seo-shared 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Descoped
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/document-metadata.d.ts

@@ -0,0 +1,7 @@
+import type { SeoConfigData } from './seo-config-types.js';
+/** Optional document-owned graph data. The CMS stores this ordinary portable contract. */
+export declare const DOCUMENT_SEO_METADATA_SCHEMA: Record<string, unknown>;
+/** Scope policy is dynamic context; the document's own overrides come from its revision. */
+export declare function documentSeoConfig(metadata: Readonly<Record<string, Record<string, unknown>>>): SeoConfigData | null;
+export declare function documentSeoProperties(metadata: Readonly<Record<string, Record<string, unknown>>>): Record<string, unknown>;
+//# sourceMappingURL=document-metadata.d.ts.map

package/dist/document-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-metadata.d.ts","sourceRoot":"","sources":["../src/document-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAE1D,0FAA0F;AAC1F,eAAO,MAAM,4BAA4B,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAqChE,CAAA;AAED,4FAA4F;AAC5F,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GAC1D,aAAa,GAAG,IAAI,CAItB;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GAC1D,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAczB"}

package/dist/document-metadata.js

@@ -0,0 +1,62 @@
+/** Optional document-owned graph data. The CMS stores this ordinary portable contract. */
+export const DOCUMENT_SEO_METADATA_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        entities: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    '@type': { type: 'string' },
+                    '@id': { type: 'string' },
+                    role: { type: 'string' },
+                    properties: { type: 'object', additionalProperties: {} },
+                },
+                required: ['@type', 'properties'],
+            },
+        },
+        fieldMappings: { type: 'object', additionalProperties: { type: 'string' } },
+        structure: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                kind: { type: 'string' },
+                trail: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: { name: { type: 'string' }, url: { type: 'string' } },
+                        required: ['name'],
+                    },
+                },
+            },
+        },
+    },
+    required: ['entities'],
+};
+/** Scope policy is dynamic context; the document's own overrides come from its revision. */
+export function documentSeoConfig(metadata) {
+    const group = metadata['seo'];
+    if (!group || !Array.isArray(group['entities']))
+        return null;
+    return group;
+}
+export function documentSeoProperties(metadata) {
+    const graph = documentSeoConfig(metadata)?.entities[0]?.properties ?? {};
+    const sharing = metadata['sharing'] ?? {};
+    const editorial = metadata['editorial'] ?? {};
+    const publication = metadata['publication'] ?? {};
+    return {
+        ...graph,
+        ...(sharing['title'] !== undefined ? { headline: sharing['title'] } : {}),
+        ...(sharing['description'] !== undefined ? { description: sharing['description'] } : {}),
+        ...(sharing['image'] !== undefined ? { image: sharing['image'] } : {}),
+        ...(sharing['canonicalUrl'] !== undefined ? { url: sharing['canonicalUrl'] } : {}),
+        ...(editorial['byline'] !== undefined ? { author: editorial['byline'] } : {}),
+        ...(publication['date'] !== undefined ? { datePublished: publication['date'] } : {}),
+    };
+}
+//# sourceMappingURL=document-metadata.js.map

package/dist/document-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-metadata.js","sourceRoot":"","sources":["../src/document-metadata.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { DOCUMENT_SEO_METADATA_SCHEMA, documentSeoConfig, documentSeoProperties, } from './document-metadata.js';
+export { serializeJsonLd } from './json-ld-serialize.js';
+export { resolveEffectiveTypes, type ScopeWithEntities, } from './resolve-effective-types.js';
+export { inferSeoConfigScope, type SeoConfigData, type SeoConfigEntity, type SeoStructureDefaults, } from './seo-config-types.js';
+export { buildSeoFieldMap, resolveSeoField, SEO_FIELD_CANDIDATES, type SeoFieldConcept, type SeoFieldMap, } from './seo-field-map.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,4BAA4B,EAC5B,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,EACL,qBAAqB,EACrB,KAAK,iBAAiB,GACvB,MAAM,8BAA8B,CAAA;AACrC,OAAO,EACL,mBAAmB,EACnB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,oBAAoB,GAC1B,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,WAAW,GACjB,MAAM,oBAAoB,CAAA"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { DOCUMENT_SEO_METADATA_SCHEMA, documentSeoConfig, documentSeoProperties, } from './document-metadata.js';
+export { serializeJsonLd } from './json-ld-serialize.js';
+export { resolveEffectiveTypes, } from './resolve-effective-types.js';
+export { inferSeoConfigScope, } from './seo-config-types.js';
+export { buildSeoFieldMap, resolveSeoField, SEO_FIELD_CANDIDATES, } from './seo-field-map.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,4BAA4B,EAC5B,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,EACL,qBAAqB,GAEtB,MAAM,8BAA8B,CAAA;AACrC,OAAO,EACL,mBAAmB,GAIpB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,oBAAoB,GAGrB,MAAM,oBAAoB,CAAA"}

package/dist/json-ld-serialize.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Serialize a JSON-LD value for embedding inside a `<script type="application/ld+json">` tag.
+ *
+ * Escapes `<` to `\u003c` to prevent premature tag termination — the standard
+ * XSS mitigation for inline JSON-LD. Every framework component that emits a
+ * JSON-LD script tag needs this exact escape; previously four copies of
+ * `JSON.stringify(data).replace(/</g, '\\u003c')` were maintained independently
+ * in `@krantho/seo` (two files), `@krantho/ui-react` (one file), and
+ * `@krantho/ui-svelte` (one file). Consolidating here eliminates the drift risk.
+ *
+ * Note: the `>` and `&` characters are intentionally NOT escaped — JSON never
+ * produces a bare `>` inside string values (it escapes them as part of normal
+ * JSON), and `&` is safe inside `<script>` content because script bodies are
+ * not parsed as HTML entities.
+ */
+export declare function serializeJsonLd(data: unknown): string;
+//# sourceMappingURL=json-ld-serialize.d.ts.map

package/dist/json-ld-serialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-ld-serialize.d.ts","sourceRoot":"","sources":["../src/json-ld-serialize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAErD"}

package/dist/json-ld-serialize.js

@@ -0,0 +1,19 @@
+/**
+ * Serialize a JSON-LD value for embedding inside a `<script type="application/ld+json">` tag.
+ *
+ * Escapes `<` to `\u003c` to prevent premature tag termination — the standard
+ * XSS mitigation for inline JSON-LD. Every framework component that emits a
+ * JSON-LD script tag needs this exact escape; previously four copies of
+ * `JSON.stringify(data).replace(/</g, '\\u003c')` were maintained independently
+ * in `@krantho/seo` (two files), `@krantho/ui-react` (one file), and
+ * `@krantho/ui-svelte` (one file). Consolidating here eliminates the drift risk.
+ *
+ * Note: the `>` and `&` characters are intentionally NOT escaped — JSON never
+ * produces a bare `>` inside string values (it escapes them as part of normal
+ * JSON), and `&` is safe inside `<script>` content because script bodies are
+ * not parsed as HTML entities.
+ */
+export function serializeJsonLd(data) {
+    return JSON.stringify(data).replace(/</g, '\\u003c');
+}
+//# sourceMappingURL=json-ld-serialize.js.map

package/dist/json-ld-serialize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-ld-serialize.js","sourceRoot":"","sources":["../src/json-ld-serialize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,eAAe,CAAC,IAAa;IAC3C,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,SAAS,CAAC,CAAA;AACtD,CAAC"}

package/dist/resolve-effective-types.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Resolve the effective Schema.org types for a document by cascading
+ * through the scope hierarchy: document → collection → site.
+ *
+ * The first scope with configured entity types wins. If no scope has
+ * types, returns an empty array.
+ */
+export interface ScopeWithEntities {
+    readonly entities: readonly {
+        readonly '@type': string;
+    }[];
+}
+export declare function resolveEffectiveTypes(document: ScopeWithEntities | null, collection: ScopeWithEntities | null, site: ScopeWithEntities | null): readonly string[];
+//# sourceMappingURL=resolve-effective-types.d.ts.map

package/dist/resolve-effective-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-effective-types.d.ts","sourceRoot":"","sources":["../src/resolve-effective-types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,SAAS;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CAC3D;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,EAClC,UAAU,EAAE,iBAAiB,GAAG,IAAI,EACpC,IAAI,EAAE,iBAAiB,GAAG,IAAI,GAC7B,SAAS,MAAM,EAAE,CAQnB"}

package/dist/resolve-effective-types.js

@@ -0,0 +1,13 @@
+export function resolveEffectiveTypes(document, collection, site) {
+    const docTypes = document?.entities.map((e) => e['@type']) ?? [];
+    if (docTypes.length > 0)
+        return docTypes;
+    const colTypes = collection?.entities.map((e) => e['@type']) ?? [];
+    if (colTypes.length > 0)
+        return colTypes;
+    const siteTypes = site?.entities.map((e) => e['@type']) ?? [];
+    if (siteTypes.length > 0)
+        return siteTypes;
+    return [];
+}
+//# sourceMappingURL=resolve-effective-types.js.map

package/dist/resolve-effective-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-effective-types.js","sourceRoot":"","sources":["../src/resolve-effective-types.ts"],"names":[],"mappings":"AAWA,MAAM,UAAU,qBAAqB,CACnC,QAAkC,EAClC,UAAoC,EACpC,IAA8B;IAE9B,MAAM,QAAQ,GAAG,QAAQ,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAA;IAChE,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,QAAQ,CAAA;IACxC,MAAM,QAAQ,GAAG,UAAU,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAA;IAClE,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,QAAQ,CAAA;IACxC,MAAM,SAAS,GAAG,IAAI,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAA;IAC7D,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,SAAS,CAAA;IAC1C,OAAO,EAAE,CAAA;AACX,CAAC"}

package/dist/seo-config-types.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Canonical SEO configuration types.
+ *
+ * These are the single source of truth for the entity/config shape used
+ * across all packages: persistence adapters, SEO graph composition, the
+ * Studio, and the API handlers.
+ */
+/** A single Schema.org entity in the SEO configuration. */
+export interface SeoConfigEntity {
+    readonly '@type': string;
+    readonly '@id'?: string | undefined;
+    readonly role?: string | undefined;
+    readonly properties: Readonly<Record<string, unknown>>;
+}
+/**
+ * The page structure a scope gives its pages when their template states none:
+ * the trail above them, root first (the page itself is added), and their kind.
+ */
+export interface SeoStructureDefaults {
+    readonly trail?: ReadonlyArray<{
+        readonly name: string;
+        readonly url?: string | undefined;
+    }> | undefined;
+    readonly kind?: string | undefined;
+}
+/** SEO configuration data — the content stored per scope (site/collection/document/route). */
+export interface SeoConfigData {
+    readonly entities: readonly SeoConfigEntity[];
+    readonly fieldMappings?: Readonly<Record<string, string>> | undefined;
+    readonly structure?: SeoStructureDefaults | undefined;
+    /**
+     * Site scope only: a robots.txt body served verbatim in place of the
+     * generated one. Kept beside the entities, never among them, so no page's
+     * structured data states it.
+     */
+    readonly robotsTxt?: string | undefined;
+}
+/** Infer SEO config scope from a config ID. */
+export declare function inferSeoConfigScope(id: string): 'site' | 'collection' | 'document' | 'route';
+//# sourceMappingURL=seo-config-types.d.ts.map

package/dist/seo-config-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seo-config-types.d.ts","sourceRoot":"","sources":["../src/seo-config-types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CACvD;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,CAAC,EACX,aAAa,CAAC;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,CAAC,GAC3E,SAAS,CAAA;IACb,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACnC;AAED,8FAA8F;AAC9F,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAA;IAC7C,QAAQ,CAAC,aAAa,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,CAAA;IACrE,QAAQ,CAAC,SAAS,CAAC,EAAE,oBAAoB,GAAG,SAAS,CAAA;IACrD;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACxC;AAED,+CAA+C;AAC/C,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,YAAY,GAAG,UAAU,GAAG,OAAO,CAM5F"}

package/dist/seo-config-types.js

@@ -0,0 +1,20 @@
+/**
+ * Canonical SEO configuration types.
+ *
+ * These are the single source of truth for the entity/config shape used
+ * across all packages: persistence adapters, SEO graph composition, the
+ * Studio, and the API handlers.
+ */
+/** Infer SEO config scope from a config ID. */
+export function inferSeoConfigScope(id) {
+    if (id === 'site')
+        return 'site';
+    if (id.startsWith('collection:'))
+        return 'collection';
+    if (id.startsWith('route:'))
+        return 'route';
+    if (id.startsWith('doc:'))
+        return 'document';
+    return 'document';
+}
+//# sourceMappingURL=seo-config-types.js.map

package/dist/seo-config-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seo-config-types.js","sourceRoot":"","sources":["../src/seo-config-types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAkCH,+CAA+C;AAC/C,MAAM,UAAU,mBAAmB,CAAC,EAAU;IAC5C,IAAI,EAAE,KAAK,MAAM;QAAE,OAAO,MAAM,CAAA;IAChC,IAAI,EAAE,CAAC,UAAU,CAAC,aAAa,CAAC;QAAE,OAAO,YAAY,CAAA;IACrD,IAAI,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,OAAO,CAAA;IAC3C,IAAI,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC;QAAE,OAAO,UAAU,CAAA;IAC5C,OAAO,UAAU,CAAA;AACnB,CAAC"}

package/dist/seo-field-map.d.ts

@@ -0,0 +1,71 @@
+/**
+ * SEO field map — resolves SEO concepts to actual CMS field names.
+ *
+ * Given the CMS field names from a collection schema, determines which
+ * CMS field serves each SEO concept (description, title, author, etc.).
+ * The CMS schema is the source of truth — SEO adapts to it.
+ *
+ * This module is the canonical implementation. It lives in @krantho/seo-shared
+ * (a zero-dependency package) so it can be consumed by any package that needs
+ * field discovery without forcing a dependency on @krantho/seo (which is
+ * optional). @krantho/seo re-exports from here for backwards compatibility.
+ */
+/** All SEO concepts that can be mapped to CMS fields */
+export interface SeoFieldMap {
+    /** CMS field that serves as the page title */
+    title: string | null;
+    /** CMS field that serves as the SEO description (meta-description > description) */
+    description: string | null;
+    /** CMS field for the author */
+    author: string | null;
+    /** CMS field for the publication date */
+    datePublished: string | null;
+    /** CMS field for the primary image */
+    image: string | null;
+    /** CMS field for canonical URL override */
+    canonicalUrl: string | null;
+    /** CMS field for robots index directive */
+    robotsIndex: string | null;
+    /** CMS field for robots follow directive */
+    robotsFollow: string | null;
+    /** CMS field for OG title override */
+    ogTitle: string | null;
+    /** CMS field for OG description override */
+    ogDescription: string | null;
+    /** CMS field for OG image override */
+    ogImage: string | null;
+    /** CMS field for OG type override */
+    ogType: string | null;
+}
+/** Type alias for an SEO concept name */
+export type SeoFieldConcept = keyof SeoFieldMap;
+/**
+ * Well-known SEO field candidates in priority order (highest first).
+ *
+ * When extending this list, add the most specific name first. The first
+ * candidate found in the CMS schema wins.
+ *
+ * Note on `image` vs `ogImage` overlap: both list `og-image` first by design.
+ * If a CMS schema has only an `og-image` field, both the canonical page image
+ * (used for JSON-LD) and the social-share image (used for og:image meta tags)
+ * should resolve to it. Authors who want different values can add a separate
+ * `image` or `hero-image` field — `image` will then prefer that and `ogImage`
+ * will continue to use `og-image`.
+ */
+export declare const SEO_FIELD_CANDIDATES: Record<SeoFieldConcept, readonly string[]>;
+/**
+ * Build an SEO field map from the CMS fields actually present in a collection.
+ *
+ * The CMS schema is the source of truth. This function discovers which
+ * fields exist and maps them to SEO concepts. If a field doesn't exist
+ * in the schema, the SEO concept maps to null.
+ */
+export declare function buildSeoFieldMap(cmsFieldNames: readonly string[]): SeoFieldMap;
+/**
+ * Resolve an SEO concept's value from CMS content fields.
+ *
+ * Uses the field map to find the right CMS field, then reads the value.
+ * Returns empty string if no field is mapped or value is missing.
+ */
+export declare function resolveSeoField(fieldMap: SeoFieldMap, concept: SeoFieldConcept, fields: Record<string, unknown>): string;
+//# sourceMappingURL=seo-field-map.d.ts.map

package/dist/seo-field-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seo-field-map.d.ts","sourceRoot":"","sources":["../src/seo-field-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,wDAAwD;AACxD,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,oFAAoF;IACpF,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,+BAA+B;IAC/B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,yCAAyC;IACzC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,sCAAsC;IACtC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,2CAA2C;IAC3C,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,2CAA2C;IAC3C,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,4CAA4C;IAC5C,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,sCAAsC;IACtC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,4CAA4C;IAC5C,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,sCAAsC;IACtC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,qCAAqC;IACrC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CACtB;AAED,yCAAyC;AACzC,MAAM,MAAM,eAAe,GAAG,MAAM,WAAW,CAAA;AAE/C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAa3E,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,WAAW,CAqB9E;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE,eAAe,EACxB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,MAAM,CAKR"}

package/dist/seo-field-map.js

@@ -0,0 +1,80 @@
+/**
+ * SEO field map — resolves SEO concepts to actual CMS field names.
+ *
+ * Given the CMS field names from a collection schema, determines which
+ * CMS field serves each SEO concept (description, title, author, etc.).
+ * The CMS schema is the source of truth — SEO adapts to it.
+ *
+ * This module is the canonical implementation. It lives in @krantho/seo-shared
+ * (a zero-dependency package) so it can be consumed by any package that needs
+ * field discovery without forcing a dependency on @krantho/seo (which is
+ * optional). @krantho/seo re-exports from here for backwards compatibility.
+ */
+/**
+ * Well-known SEO field candidates in priority order (highest first).
+ *
+ * When extending this list, add the most specific name first. The first
+ * candidate found in the CMS schema wins.
+ *
+ * Note on `image` vs `ogImage` overlap: both list `og-image` first by design.
+ * If a CMS schema has only an `og-image` field, both the canonical page image
+ * (used for JSON-LD) and the social-share image (used for og:image meta tags)
+ * should resolve to it. Authors who want different values can add a separate
+ * `image` or `hero-image` field — `image` will then prefer that and `ogImage`
+ * will continue to use `og-image`.
+ */
+export const SEO_FIELD_CANDIDATES = {
+    title: ['title', 'name'],
+    description: ['meta-description', 'description', 'ingress', 'excerpt'],
+    author: ['author'],
+    datePublished: ['published-date', 'date'],
+    image: ['og-image', 'image', 'hero-image'],
+    canonicalUrl: ['canonical-url'],
+    robotsIndex: ['robots-index'],
+    robotsFollow: ['robots-follow'],
+    ogTitle: ['og-title'],
+    ogDescription: ['og-description'],
+    ogImage: ['og-image', 'image'],
+    ogType: ['og-type'],
+};
+/**
+ * Build an SEO field map from the CMS fields actually present in a collection.
+ *
+ * The CMS schema is the source of truth. This function discovers which
+ * fields exist and maps them to SEO concepts. If a field doesn't exist
+ * in the schema, the SEO concept maps to null.
+ */
+export function buildSeoFieldMap(cmsFieldNames) {
+    const fieldSet = new Set(cmsFieldNames);
+    function resolve(candidates) {
+        return candidates.find((f) => fieldSet.has(f)) ?? null;
+    }
+    return {
+        title: resolve(SEO_FIELD_CANDIDATES.title),
+        description: resolve(SEO_FIELD_CANDIDATES.description),
+        author: resolve(SEO_FIELD_CANDIDATES.author),
+        datePublished: resolve(SEO_FIELD_CANDIDATES.datePublished),
+        image: resolve(SEO_FIELD_CANDIDATES.image),
+        canonicalUrl: resolve(SEO_FIELD_CANDIDATES.canonicalUrl),
+        robotsIndex: resolve(SEO_FIELD_CANDIDATES.robotsIndex),
+        robotsFollow: resolve(SEO_FIELD_CANDIDATES.robotsFollow),
+        ogTitle: resolve(SEO_FIELD_CANDIDATES.ogTitle),
+        ogDescription: resolve(SEO_FIELD_CANDIDATES.ogDescription),
+        ogImage: resolve(SEO_FIELD_CANDIDATES.ogImage),
+        ogType: resolve(SEO_FIELD_CANDIDATES.ogType),
+    };
+}
+/**
+ * Resolve an SEO concept's value from CMS content fields.
+ *
+ * Uses the field map to find the right CMS field, then reads the value.
+ * Returns empty string if no field is mapped or value is missing.
+ */
+export function resolveSeoField(fieldMap, concept, fields) {
+    const cmsField = fieldMap[concept];
+    if (!cmsField)
+        return '';
+    const value = fields[cmsField];
+    return typeof value === 'string' && value.length > 0 ? value : '';
+}
+//# sourceMappingURL=seo-field-map.js.map

package/dist/seo-field-map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seo-field-map.js","sourceRoot":"","sources":["../src/seo-field-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAiCH;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA+C;IAC9E,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,CAAC,kBAAkB,EAAE,aAAa,EAAE,SAAS,EAAE,SAAS,CAAC;IACtE,MAAM,EAAE,CAAC,QAAQ,CAAC;IAClB,aAAa,EAAE,CAAC,gBAAgB,EAAE,MAAM,CAAC;IACzC,KAAK,EAAE,CAAC,UAAU,EAAE,OAAO,EAAE,YAAY,CAAC;IAC1C,YAAY,EAAE,CAAC,eAAe,CAAC;IAC/B,WAAW,EAAE,CAAC,cAAc,CAAC;IAC7B,YAAY,EAAE,CAAC,eAAe,CAAC;IAC/B,OAAO,EAAE,CAAC,UAAU,CAAC;IACrB,aAAa,EAAE,CAAC,gBAAgB,CAAC;IACjC,OAAO,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC9B,MAAM,EAAE,CAAC,SAAS,CAAC;CACpB,CAAA;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,aAAgC;IAC/D,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,aAAa,CAAC,CAAA;IAEvC,SAAS,OAAO,CAAC,UAA6B;QAC5C,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAA;IACxD,CAAC;IAED,OAAO;QACL,KAAK,EAAE,OAAO,CAAC,oBAAoB,CAAC,KAAK,CAAC;QAC1C,WAAW,EAAE,OAAO,CAAC,oBAAoB,CAAC,WAAW,CAAC;QACtD,MAAM,EAAE,OAAO,CAAC,oBAAoB,CAAC,MAAM,CAAC;QAC5C,aAAa,EAAE,OAAO,CAAC,oBAAoB,CAAC,aAAa,CAAC;QAC1D,KAAK,EAAE,OAAO,CAAC,oBAAoB,CAAC,KAAK,CAAC;QAC1C,YAAY,EAAE,OAAO,CAAC,oBAAoB,CAAC,YAAY,CAAC;QACxD,WAAW,EAAE,OAAO,CAAC,oBAAoB,CAAC,WAAW,CAAC;QACtD,YAAY,EAAE,OAAO,CAAC,oBAAoB,CAAC,YAAY,CAAC;QACxD,OAAO,EAAE,OAAO,CAAC,oBAAoB,CAAC,OAAO,CAAC;QAC9C,aAAa,EAAE,OAAO,CAAC,oBAAoB,CAAC,aAAa,CAAC;QAC1D,OAAO,EAAE,OAAO,CAAC,oBAAoB,CAAC,OAAO,CAAC;QAC9C,MAAM,EAAE,OAAO,CAAC,oBAAoB,CAAC,MAAM,CAAC;KAC7C,CAAA;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAqB,EACrB,OAAwB,EACxB,MAA+B;IAE/B,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAA;IAClC,IAAI,CAAC,QAAQ;QAAE,OAAO,EAAE,CAAA;IACxB,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAA;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAA;AACnE,CAAC"}

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@krantho/seo-shared",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "license": "MIT",
+  "homepage": "https://krantho.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/descoped/krantho.git",
+    "directory": "packages/seo-shared"
+  },
+  "bugs": {
+    "url": "https://github.com/descoped/krantho/issues"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.