@krantho/seo 0.0.0-stage → 1.0.0

package/dist/graph/compose-from-config.d.ts

@@ -0,0 +1,89 @@
+import type { PageStructure } from '@krantho/core';
+import type { SeoConfigData } from '@krantho/seo-shared';
+import type { FindingSink } from './resolve-references.js';
+import '../decorators/index.js';
+import type { EntityLevel, ResolvedProperty } from '../types/definition.js';
+import type { JsonLdGraph, SeoGraphConfig } from './types.js';
+import { type ValueScope } from './value-scope.js';
+/** Document metadata from the CMS persistence layer */
+export interface DocumentMeta {
+    /** First version creation timestamp (ISO 8601) */
+    createdAt: string;
+    /** Latest version creation timestamp (ISO 8601) */
+    updatedAt?: string | undefined;
+    /** Document locale */
+    locale: string;
+    /** Current version number */
+    version: number;
+}
+/** Options for config-driven graph composition */
+export interface ComposeFromConfigOptions {
+    /** Effective document-level SEO config (resolved from collection → route → document chain) */
+    config: SeoConfigData;
+    /** Page fields from CMS */
+    fields: Record<string, unknown>;
+    /** Site configuration (identity, domain, language, baseUrl) */
+    siteConfig: SeoGraphConfig;
+    /** Current page path */
+    path: string;
+    /** Site-level SEO config — entities rendered alongside document entities */
+    siteLevel?: SeoConfigData | null | undefined;
+    /** Document metadata for system-derived properties */
+    documentMeta?: DocumentMeta | undefined;
+    /**
+     * The structure the page's template renders — its trail, its place in a
+     * sequence, its kind. The effective configuration's `structure` gives a
+     * trail above the page and a kind when the template states none.
+     */
+    structure?: PageStructure | undefined;
+    /** Question and answer pairs the page renders */
+    faq?: ReadonlyArray<{
+        question: string;
+        answer: string;
+    }> | undefined;
+    /** Receives what composition left out because the site configures nothing to refer to */
+    onFinding?: FindingSink | undefined;
+}
+/** A property's effective value as an editor sees it */
+export interface ResolvedPropertyView {
+    readonly property: string;
+    readonly value: unknown;
+    readonly source: ResolvedProperty['source'];
+    /** The site, collection, URL pattern or document that set the value; computed; or a link to another entity */
+    readonly scope: ValueScope;
+    /** Where the value was read or how it was computed */
+    readonly origin: string;
+    /** Whether the SEO settings may set it; references the type's structure depends on may not */
+    readonly editable: boolean;
+}
+/** An entity of a page with its resolved properties */
+export interface ResolvedEntity {
+    readonly type: string;
+    readonly id: string;
+    readonly level: EntityLevel;
+    readonly properties: readonly ResolvedPropertyView[];
+}
+/**
+ * What every entity of a page resolves to — each property's value, its
+ * source and whether the SEO settings may override it — from the same inputs
+ * and in the same order `composeFromConfig` uses, so an editor sees what the
+ * page emits and where each value comes from.
+ */
+export declare function resolvePageEntities(options: Omit<ComposeFromConfigOptions, 'onFinding'>): ResolvedEntity[];
+/**
+ * Compose a page's JSON-LD `@graph` from its SEO configuration:
+ *
+ * 1. Site entities (the site's organization, WebSite, Person) from the
+ *    site-level configuration and the site's identity.
+ * 2. Document entities (Article, Service …) from the effective document
+ *    configuration, the content fields and values computed from the page.
+ * 3. Every reference a type emits resolved within the graph — to a site
+ *    entity of an acceptable type, or left out with a finding.
+ *
+ * Each property's value comes from one source in a fixed order (see
+ * `resolveProperties`). An author comes from content fields, field mappings
+ * or configuration — never from version history, whose editor identity is
+ * private.
+ */
+export declare function composeFromConfig(options: ComposeFromConfigOptions): JsonLdGraph;
+//# sourceMappingURL=compose-from-config.d.ts.map

package/dist/graph/compose-from-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose-from-config.d.ts","sourceRoot":"","sources":["../../src/graph/compose-from-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAa,MAAM,eAAe,CAAA;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAmB,MAAM,qBAAqB,CAAA;AAMzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAE1D,OAAO,wBAAwB,CAAA;AAG/B,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAI3E,OAAO,KAAK,EAAE,WAAW,EAAgB,cAAc,EAAE,MAAM,YAAY,CAAA;AAC3E,OAAO,EAAE,KAAK,UAAU,EAAc,MAAM,kBAAkB,CAAA;AAE9D,uDAAuD;AACvD,MAAM,WAAW,YAAY;IAC3B,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAA;IACjB,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAA;IACd,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,kDAAkD;AAClD,MAAM,WAAW,wBAAwB;IACvC,8FAA8F;IAC9F,MAAM,EAAE,aAAa,CAAA;IACrB,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/B,+DAA+D;IAC/D,UAAU,EAAE,cAAc,CAAA;IAC1B,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,4EAA4E;IAC5E,SAAS,CAAC,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,CAAA;IAC5C,sDAAsD;IACtD,YAAY,CAAC,EAAE,YAAY,GAAG,SAAS,CAAA;IACvC;;;;OAIG;IACH,SAAS,CAAC,EAAE,aAAa,GAAG,SAAS,CAAA;IACrC,iDAAiD;IACjD,GAAG,CAAC,EAAE,aAAa,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,SAAS,CAAA;IACrE,yFAAyF;IACzF,SAAS,CAAC,EAAE,WAAW,GAAG,SAAS,CAAA;CACpC;AA2FD,wDAAwD;AACxD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC,QAAQ,CAAC,CAAA;IAC3C,8GAA8G;IAC9G,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,8FAA8F;IAC9F,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAC3B;AAED,uDAAuD;AACvD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAA;IAC3B,QAAQ,CAAC,UAAU,EAAE,SAAS,oBAAoB,EAAE,CAAA;CACrD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,IAAI,CAAC,wBAAwB,EAAE,WAAW,CAAC,GACnD,cAAc,EAAE,CA2BlB;AAcD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,WAAW,CAehF"}

package/dist/graph/compose-from-config.js

@@ -0,0 +1,189 @@
+import { buildSeoFieldMap, resolveSeoField } from '@krantho/seo-shared';
+import { getTypeDefinition } from '../types/registry.js';
+import { buildEntity, carries, entityInputValues } from './build-entity.js';
+import { resolveReferences } from './resolve-references.js';
+import '../decorators/index.js';
+import { pageTypeFor, registeredDecorators } from '../decorators/index.js';
+import { isSubtypeOf } from '../vocabulary/index.js';
+import { documentId } from './id-conventions.js';
+import { valueScope } from './value-scope.js';
+/** Values computed from the page path and the document's version history */
+function computedValues(options) {
+    const page = `${options.siteConfig.baseUrl}${options.path}`;
+    const meta = options.documentMeta;
+    return {
+        url: page,
+        mainEntityOfPage: page,
+        datePublished: meta?.createdAt,
+        dateModified: meta ? (meta.updatedAt ?? meta.createdAt) : undefined,
+        inLanguage: meta?.locale,
+    };
+}
+/** A site entity: the SEO settings and the site configuration, no page content */
+function siteEntityInput(entity, site) {
+    return {
+        type: entity['@type'],
+        level: 'site',
+        id: entity['@id'],
+        configured: entity.properties,
+        fields: {},
+        computed: {},
+        site,
+        path: '',
+    };
+}
+/** A document entity; a type defined for the whole site keeps its site-wide `@id` */
+function documentEntityInput(entity, options) {
+    const type = entity['@type'];
+    const { fields } = options;
+    return {
+        type,
+        level: getTypeDefinition(type)?.scope === 'site' ? 'site' : 'document',
+        id: entity['@id'],
+        configured: entity.properties,
+        fields,
+        fieldMappings: options.config.fieldMappings,
+        computed: computedValues(options),
+        site: options.siteConfig,
+        path: options.path,
+        title: pageTitle(fields),
+        faq: options.faq,
+        trail: pageStructure(options).trail,
+    };
+}
+/** A trail or sequence URL made absolute against the site's base URL */
+function absolute(url, site) {
+    return url.startsWith('/') ? `${site.baseUrl}${url}` : url;
+}
+/** The page's title, as its content states it */
+function pageTitle(fields) {
+    return resolveSeoField(buildSeoFieldMap(Object.keys(fields)), 'title', fields) || undefined;
+}
+/**
+ * The page's structure with absolute URLs: the template's trail, else the
+ * configured trail above the page followed by the page; the template's kind,
+ * else the configured one. The trail's last step links to the page.
+ */
+function pageStructure(options) {
+    const { siteConfig: site, structure, config } = options;
+    const page = `${site.baseUrl}${options.path}`;
+    const steps = structure?.trail?.length
+        ? structure.trail
+        : config.structure?.trail?.length
+            ? [...config.structure.trail, { name: pageTitle(options.fields) ?? '', url: page }]
+            : undefined;
+    const trail = steps?.map((step, index) => {
+        const url = step.url ?? (index === steps.length - 1 ? page : undefined);
+        return { name: step.name, ...(url ? { url: absolute(url, site) } : {}) };
+    });
+    const sequence = structure?.sequence && {
+        partOf: { ...structure.sequence.partOf, url: absolute(structure.sequence.partOf.url, site) },
+        position: structure.sequence.position,
+    };
+    const kind = structure?.kind ?? config.structure?.kind;
+    return {
+        ...(trail ? { trail } : {}),
+        ...(sequence ? { sequence } : {}),
+        ...(kind ? { kind } : {}),
+    };
+}
+/**
+ * What every entity of a page resolves to — each property's value, its
+ * source and whether the SEO settings may override it — from the same inputs
+ * and in the same order `composeFromConfig` uses, so an editor sees what the
+ * page emits and where each value comes from.
+ */
+export function resolvePageEntities(options) {
+    const inputs = [
+        ...(options.siteLevel?.entities ?? []).map((entity) => ({
+            input: siteEntityInput(entity, options.siteConfig),
+            from: { fromSite: true },
+        })),
+        ...options.config.entities.map((entity) => ({
+            input: documentEntityInput(entity, options),
+            from: { fromSite: false, scopes: entity.scopes },
+        })),
+    ];
+    return inputs.map(({ input, from }) => {
+        const { id, values, definition } = entityInputValues(input);
+        const fixed = new Set(Object.keys(definition?.references ?? {}));
+        const carried = [...values].filter(([property, resolved]) => carries(property, resolved, input.type, definition));
+        const properties = carried.map(([property, resolved]) => ({
+            property,
+            value: resolved.value,
+            source: resolved.source,
+            scope: valueScope(resolved, property, from),
+            origin: resolved.origin,
+            editable: !fixed.has(property),
+        }));
+        return { type: input.type, id, level: input.level, properties };
+    });
+}
+/** One node per `@id` — a later entity replaces an earlier one */
+function deduplicate(nodes) {
+    const byId = new Map();
+    const withoutId = [];
+    for (const node of nodes) {
+        const id = node.entity['@id'];
+        if (typeof id === 'string')
+            byId.set(id, node);
+        else
+            withoutId.push(node);
+    }
+    return [...byId.values(), ...withoutId];
+}
+/**
+ * Compose a page's JSON-LD `@graph` from its SEO configuration:
+ *
+ * 1. Site entities (the site's organization, WebSite, Person) from the
+ *    site-level configuration and the site's identity.
+ * 2. Document entities (Article, Service …) from the effective document
+ *    configuration, the content fields and values computed from the page.
+ * 3. Every reference a type emits resolved within the graph — to a site
+ *    entity of an acceptable type, or left out with a finding.
+ *
+ * Each property's value comes from one source in a fixed order (see
+ * `resolveProperties`). An author comes from content fields, field mappings
+ * or configuration — never from version history, whose editor identity is
+ * private.
+ */
+export function composeFromConfig(options) {
+    const siteEntities = (options.siteLevel?.entities ?? []).map((entity) => buildEntity(siteEntityInput(entity, options.siteConfig)));
+    const documentEntities = options.config.entities.map((entity) => buildEntity(documentEntityInput(entity, options)));
+    const nodes = deduplicate([...siteEntities, ...documentEntities]);
+    const graph = resolveReferences(nodes, options.onFinding);
+    const page = pageContext(options, documentEntities);
+    const decorated = registeredDecorators().reduce((current, decorator) => decorator.decorate(current, page), graph);
+    return { '@context': 'https://schema.org', '@graph': decorated };
+}
+/** The page the decorators describe: its page node, its main entity and its structure */
+function pageContext(options, documentEntities) {
+    const { siteConfig: site, path } = options;
+    const structure = pageStructure(options);
+    if (structure.kind !== undefined && !pageTypeFor(structure.kind)) {
+        options.onFinding?.({
+            severity: 'warning',
+            code: 'unknown-type',
+            profile: 'schema.org',
+            message: `The page kind "${structure.kind}" is neither a known kind nor a current Schema.org WebPage type; the page is a WebPage.`,
+        });
+    }
+    const isPage = (entity) => typeof entity['@type'] === 'string' && isSubtypeOf(entity['@type'], 'WebPage');
+    const pageNode = documentEntities.find((node) => node.level === 'document' && isPage(node.entity));
+    const main = documentEntities.find((node) => node.level === 'document' &&
+        !isPage(node.entity) &&
+        !isSubtypeOf(String(node.entity['@type']), 'BreadcrumbList'));
+    const computed = computedValues(options);
+    return {
+        ...structure,
+        site,
+        path,
+        url: `${site.baseUrl}${path}`,
+        pageId: pageNode?.entity['@id'] ?? documentId(site.baseUrl, path, 'webpage'),
+        mainEntityId: main?.entity['@id'],
+        title: pageTitle(options.fields),
+        language: computed.inLanguage ?? site.language,
+        dateModified: typeof computed.dateModified === 'string' ? computed.dateModified : undefined,
+    };
+}
+//# sourceMappingURL=compose-from-config.js.map

package/dist/graph/compose-from-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose-from-config.js","sourceRoot":"","sources":["../../src/graph/compose-from-config.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAExD,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAG3E,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAC3D,OAAO,wBAAwB,CAAA;AAE/B,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAA;AAE1E,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAA;AAEpD,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAEhD,OAAO,EAAmB,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAwC9D,4EAA4E;AAC5E,SAAS,cAAc,CAAC,OAAiC;IACvD,MAAM,IAAI,GAAG,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,CAAA;IAC3D,MAAM,IAAI,GAAG,OAAO,CAAC,YAAY,CAAA;IACjC,OAAO;QACL,GAAG,EAAE,IAAI;QACT,gBAAgB,EAAE,IAAI;QACtB,aAAa,EAAE,IAAI,EAAE,SAAS;QAC9B,YAAY,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS;QACnE,UAAU,EAAE,IAAI,EAAE,MAAM;KACzB,CAAA;AACH,CAAC;AAED,kFAAkF;AAClF,SAAS,eAAe,CAAC,MAAuB,EAAE,IAAoB;IACpE,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC;QACrB,KAAK,EAAE,MAAM;QACb,EAAE,EAAE,MAAM,CAAC,KAAK,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,MAAM,EAAE,EAAE;QACV,QAAQ,EAAE,EAAE;QACZ,IAAI;QACJ,IAAI,EAAE,EAAE;KACT,CAAA;AACH,CAAC;AAED,qFAAqF;AACrF,SAAS,mBAAmB,CAC1B,MAAuB,EACvB,OAAiC;IAEjC,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,CAAA;IAC5B,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAA;IAC1B,OAAO;QACL,IAAI;QACJ,KAAK,EAAE,iBAAiB,CAAC,IAAI,CAAC,EAAE,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU;QACtE,EAAE,EAAE,MAAM,CAAC,KAAK,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,MAAM;QACN,aAAa,EAAE,OAAO,CAAC,MAAM,CAAC,aAAa;QAC3C,QAAQ,EAAE,cAAc,CAAC,OAAO,CAAC;QACjC,IAAI,EAAE,OAAO,CAAC,UAAU;QACxB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC;QACxB,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC,KAAK;KACpC,CAAA;AACH,CAAC;AAED,wEAAwE;AACxE,SAAS,QAAQ,CAAC,GAAW,EAAE,IAAoB;IACjD,OAAO,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,OAAO,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAA;AAC5D,CAAC;AAED,iDAAiD;AACjD,SAAS,SAAS,CAAC,MAA+B;IAChD,OAAO,eAAe,CAAC,gBAAgB,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,IAAI,SAAS,CAAA;AAC7F,CAAC;AAED;;;;GAIG;AACH,SAAS,aAAa,CAAC,OAAiC;IACtD,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAA;IACvD,MAAM,IAAI,GAAG,GAAG,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,CAAA;IAC7C,MAAM,KAAK,GAAqC,SAAS,EAAE,KAAK,EAAE,MAAM;QACtE,CAAC,CAAC,SAAS,CAAC,KAAK;QACjB,CAAC,CAAC,MAAM,CAAC,SAAS,EAAE,KAAK,EAAE,MAAM;YAC/B,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;YACnF,CAAC,CAAC,SAAS,CAAA;IACf,MAAM,KAAK,GAAG,KAAK,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;QACvC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,KAAK,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;QACvE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAA;IAC1E,CAAC,CAAC,CAAA;IACF,MAAM,QAAQ,GAAG,SAAS,EAAE,QAAQ,IAAI;QACtC,MAAM,EAAE,EAAE,GAAG,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,GAAG,EAAE,QAAQ,CAAC,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE;QAC5F,QAAQ,EAAE,SAAS,CAAC,QAAQ,CAAC,QAAQ;KACtC,CAAA;IACD,MAAM,IAAI,GAAG,SAAS,EAAE,IAAI,IAAI,MAAM,CAAC,SAAS,EAAE,IAAI,CAAA;IACtD,OAAO;QACL,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3B,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACjC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC1B,CAAA;AACH,CAAC;AAuBD;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAAoD;IAEpD,MAAM,MAAM,GAAG;QACb,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,QAAQ,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YACtD,KAAK,EAAE,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC;YAClD,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;SACzB,CAAC,CAAC;QACH,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YAC1C,KAAK,EAAE,mBAAmB,CAAC,MAAM,EAAE,OAAO,CAAC;YAC3C,IAAI,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAG,MAAsC,CAAC,MAAM,EAAE;SAClF,CAAC,CAAC;KACJ,CAAA;IACD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,EAAE;QACpC,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAA;QAC3D,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,UAAU,IAAI,EAAE,CAAC,CAAC,CAAA;QAChE,MAAM,OAAO,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,EAAE,CAC1D,OAAO,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,IAAI,EAAE,UAAU,CAAC,CACpD,CAAA;QACD,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC;YACxD,QAAQ;YACR,KAAK,EAAE,QAAQ,CAAC,KAAK;YACrB,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,KAAK,EAAE,UAAU,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC;YAC3C,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,QAAQ,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC;SAC/B,CAAC,CAAC,CAAA;QACH,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,CAAA;IACjE,CAAC,CAAC,CAAA;AACJ,CAAC;AAED,kEAAkE;AAClE,SAAS,WAAW,CAAC,KAA8B;IACjD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAwB,CAAA;IAC5C,MAAM,SAAS,GAAmB,EAAE,CAAA;IACpC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QAC7B,IAAI,OAAO,EAAE,KAAK,QAAQ;YAAE,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,CAAA;;YACzC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC3B,CAAC;IACD,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,EAAE,GAAG,SAAS,CAAC,CAAA;AACzC,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAiC;IACjE,MAAM,YAAY,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,QAAQ,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CACtE,WAAW,CAAC,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC,CACzD,CAAA;IACD,MAAM,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAC9D,WAAW,CAAC,mBAAmB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAClD,CAAA;IACD,MAAM,KAAK,GAAG,WAAW,CAAC,CAAC,GAAG,YAAY,EAAE,GAAG,gBAAgB,CAAC,CAAC,CAAA;IACjE,MAAM,KAAK,GAAG,iBAAiB,CAAC,KAAK,EAAE,OAAO,CAAC,SAAS,CAAC,CAAA;IACzD,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAA;IACnD,MAAM,SAAS,GAAG,oBAAoB,EAAE,CAAC,MAAM,CAC7C,CAAC,OAAO,EAAE,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,EACzD,KAAK,CACN,CAAA;IACD,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAA;AAClE,CAAC;AAED,yFAAyF;AACzF,SAAS,WAAW,CAClB,OAAiC,EACjC,gBAAyC;IAEzC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,OAAO,CAAA;IAC1C,MAAM,SAAS,GAAG,aAAa,CAAC,OAAO,CAAC,CAAA;IACxC,IAAI,SAAS,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;QACjE,OAAO,CAAC,SAAS,EAAE,CAAC;YAClB,QAAQ,EAAE,SAAS;YACnB,IAAI,EAAE,cAAc;YACpB,OAAO,EAAE,YAAY;YACrB,OAAO,EAAE,kBAAkB,SAAS,CAAC,IAAI,yFAAyF;SACnI,CAAC,CAAA;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,CAAC,MAAoB,EAAW,EAAE,CAC/C,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC,CAAA;IAChF,MAAM,QAAQ,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,KAAK,UAAU,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAA;IAClG,MAAM,IAAI,GAAG,gBAAgB,CAAC,IAAI,CAChC,CAAC,IAAI,EAAE,EAAE,CACP,IAAI,CAAC,KAAK,KAAK,UAAU;QACzB,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;QACpB,CAAC,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,EAAE,gBAAgB,CAAC,CAC/D,CAAA;IACD,MAAM,QAAQ,GAAG,cAAc,CAAC,OAAO,CAAC,CAAA;IACxC,OAAO;QACL,GAAG,SAAS;QACZ,IAAI;QACJ,IAAI;QACJ,GAAG,EAAE,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE;QAC7B,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,SAAS,CAAC;QAC5E,YAAY,EAAE,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC;QACjC,KAAK,EAAE,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC;QAChC,QAAQ,EAAE,QAAQ,CAAC,UAAU,IAAI,IAAI,CAAC,QAAQ;QAC9C,YAAY,EAAE,OAAO,QAAQ,CAAC,YAAY,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS;KAC5F,CAAA;AACH,CAAC"}

package/dist/graph/compose-graph.d.ts

@@ -0,0 +1,40 @@
+import type { PageStructure } from '@krantho/core';
+import type { Archetype } from '../archetypes/types.js';
+import type { JsonLdGraph, SeoGraphConfig } from './types.js';
+/** Options for graph composition */
+export interface ComposeGraphOptions {
+    /** The archetype defining which schemas to render */
+    archetype: Archetype;
+    /** Page fields (resolved by resolvePageContent) */
+    fields: Record<string, unknown>;
+    /** Site configuration */
+    config: SeoGraphConfig;
+    /** Current page path, e.g., '/about' or '/blog/my-post' */
+    path: string;
+    /** The structure the page renders: its trail, its place in a sequence, its kind */
+    structure?: PageStructure | undefined;
+    /** Optional FAQ pairs for FAQPage schema */
+    faq?: ReadonlyArray<{
+        question: string;
+        answer: string;
+    }> | undefined;
+}
+/**
+ * Compose a JSON-LD @graph block from an archetype and page data: each of the
+ * archetype's types is built as configured with no settings of its own, so
+ * values come from the page's content, the page itself and the site's
+ * identity — the same composition as `composeFromConfig`.
+ *
+ * @example
+ * ```ts
+ * const graph = composeGraph({
+ *   archetype: homePageArchetype,
+ *   fields: content.hero.fields,
+ *   config: siteConfig,
+ *   path: '/',
+ * })
+ * // Returns { "@context": "https://schema.org", "@graph": [...] }
+ * ```
+ */
+export declare function composeGraph(options: ComposeGraphOptions): JsonLdGraph;
+//# sourceMappingURL=compose-graph.d.ts.map

package/dist/graph/compose-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose-graph.d.ts","sourceRoot":"","sources":["../../src/graph/compose-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AAEvD,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE7D,oCAAoC;AACpC,MAAM,WAAW,mBAAmB;IAClC,qDAAqD;IACrD,SAAS,EAAE,SAAS,CAAA;IACpB,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/B,yBAAyB;IACzB,MAAM,EAAE,cAAc,CAAA;IACtB,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAA;IACZ,mFAAmF;IACnF,SAAS,CAAC,EAAE,aAAa,GAAG,SAAS,CAAA;IACrC,4CAA4C;IAC5C,GAAG,CAAC,EAAE,aAAa,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,SAAS,CAAA;CACtE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,WAAW,CAUtE"}

package/dist/graph/compose-graph.js

@@ -0,0 +1,30 @@
+import { composeFromConfig } from './compose-from-config.js';
+/**
+ * Compose a JSON-LD @graph block from an archetype and page data: each of the
+ * archetype's types is built as configured with no settings of its own, so
+ * values come from the page's content, the page itself and the site's
+ * identity — the same composition as `composeFromConfig`.
+ *
+ * @example
+ * ```ts
+ * const graph = composeGraph({
+ *   archetype: homePageArchetype,
+ *   fields: content.hero.fields,
+ *   config: siteConfig,
+ *   path: '/',
+ * })
+ * // Returns { "@context": "https://schema.org", "@graph": [...] }
+ * ```
+ */
+export function composeGraph(options) {
+    const entities = options.archetype.schemas.map((type) => ({ '@type': type, properties: {} }));
+    return composeFromConfig({
+        config: { entities },
+        fields: options.fields,
+        siteConfig: options.config,
+        path: options.path,
+        structure: options.structure,
+        faq: options.faq,
+    });
+}
+//# sourceMappingURL=compose-graph.js.map

package/dist/graph/compose-graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose-graph.js","sourceRoot":"","sources":["../../src/graph/compose-graph.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAmB5D;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,YAAY,CAAC,OAA4B;IACvD,MAAM,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,CAAC,CAAA;IAC7F,OAAO,iBAAiB,CAAC;QACvB,MAAM,EAAE,EAAE,QAAQ,EAAE;QACpB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,UAAU,EAAE,OAAO,CAAC,MAAM;QAC1B,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,GAAG,EAAE,OAAO,CAAC,GAAG;KACjB,CAAC,CAAA;AACJ,CAAC"}

package/dist/graph/effective-config.d.ts

@@ -0,0 +1,36 @@
+import type { SeoConfigData, SeoConfigEntity } from '@krantho/seo-shared';
+/** A scope of the document-level configuration chain */
+export type ConfigScope = 'collection' | 'route' | 'document';
+/** Scope-keyed SEO config chain passed to `resolveEffectiveConfig`. */
+export interface SeoConfigChain {
+    site?: SeoConfigData | null | undefined;
+    collection?: SeoConfigData | null | undefined;
+    route?: SeoConfigData | null | undefined;
+    document?: SeoConfigData | null | undefined;
+}
+/** An entity of the effective configuration, with the scope each of its configured properties came from */
+export interface EffectiveSeoEntity extends SeoConfigEntity {
+    readonly scopes: Readonly<Record<string, ConfigScope>>;
+}
+/** The effective document-level configuration: entities merged across the chain */
+export interface EffectiveSeoConfig extends SeoConfigData {
+    readonly entities: readonly EffectiveSeoEntity[];
+}
+/**
+ * Resolve effective SEO config from the document-level scope hierarchy:
+ * collection → route → document (most specific wins).
+ *
+ * Entities are matched by `(@type, role)` tuple across scopes. When the
+ * same entity appears in multiple scopes, their properties are merged
+ * with the more specific scope's values taking precedence, and each
+ * property records the scope that gave its value.
+ *
+ * Field mappings and the page structure are merged across scopes (most
+ * specific wins).
+ *
+ * **Site scope is NOT included** — it's passed separately to
+ * `composeFromConfig` as `siteLevel` because site entities use different
+ * id conventions and builder logic.
+ */
+export declare function resolveEffectiveConfig(configs: SeoConfigChain): EffectiveSeoConfig;
+//# sourceMappingURL=effective-config.d.ts.map

package/dist/graph/effective-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effective-config.d.ts","sourceRoot":"","sources":["../../src/graph/effective-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAEzE,wDAAwD;AACxD,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,OAAO,GAAG,UAAU,CAAA;AAE7D,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,CAAA;IACvC,UAAU,CAAC,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,CAAA;IAC7C,KAAK,CAAC,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,CAAA;IACxC,QAAQ,CAAC,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,CAAA;CAC5C;AAED,2GAA2G;AAC3G,MAAM,WAAW,kBAAmB,SAAQ,eAAe;IACzD,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAA;CACvD;AAED,mFAAmF;AACnF,MAAM,WAAW,kBAAmB,SAAQ,aAAa;IACvD,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAA;CACjD;AAgBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,cAAc,GAAG,kBAAkB,CA0DlF"}

package/dist/graph/effective-config.js

@@ -0,0 +1,84 @@
+/**
+ * Unique key for an entity in the scope chain — used to match and merge
+ * entities across scopes. Entities with the same `@type` and `role` are
+ * considered the same entity.
+ */
+function entityKey(entity) {
+    return entity.role ? `${entity['@type']}:${entity.role}` : entity['@type'];
+}
+/** Each property of the entity, set by this scope */
+function scopesOf(entity, scope) {
+    return Object.fromEntries(Object.keys(entity.properties).map((property) => [property, scope]));
+}
+/**
+ * Resolve effective SEO config from the document-level scope hierarchy:
+ * collection → route → document (most specific wins).
+ *
+ * Entities are matched by `(@type, role)` tuple across scopes. When the
+ * same entity appears in multiple scopes, their properties are merged
+ * with the more specific scope's values taking precedence, and each
+ * property records the scope that gave its value.
+ *
+ * Field mappings and the page structure are merged across scopes (most
+ * specific wins).
+ *
+ * **Site scope is NOT included** — it's passed separately to
+ * `composeFromConfig` as `siteLevel` because site entities use different
+ * id conventions and builder logic.
+ */
+export function resolveEffectiveConfig(configs) {
+    const entityMap = new Map();
+    // Track insertion order: the first scope to introduce an entity determines its
+    // position. Since we iterate least-specific → most-specific, the collection
+    // scope's ordering is preserved while more specific scopes override properties.
+    const entityOrder = [];
+    // Process from least specific to most specific (so more specific overwrites)
+    const scopes = [
+        ['collection', configs.collection],
+        ['route', configs.route],
+        ['document', configs.document],
+    ];
+    for (const [scope, config] of scopes) {
+        if (!config)
+            continue;
+        for (const entity of config.entities) {
+            const key = entityKey(entity);
+            const existing = entityMap.get(key);
+            if (existing) {
+                // Merge properties: more specific scope overrides per-property
+                entityMap.set(key, {
+                    '@type': entity['@type'],
+                    ...(entity['@id'] ? { '@id': entity['@id'] } : {}),
+                    ...(entity.role ? { role: entity.role } : {}),
+                    properties: { ...existing.properties, ...entity.properties },
+                    scopes: { ...existing.scopes, ...scopesOf(entity, scope) },
+                });
+            }
+            else {
+                entityMap.set(key, { ...entity, scopes: scopesOf(entity, scope) });
+                entityOrder.push(key);
+            }
+        }
+    }
+    // Field mappings: merge across scopes (most specific wins)
+    const fieldMappings = {
+        ...(configs.collection?.fieldMappings ?? {}),
+        ...(configs.route?.fieldMappings ?? {}),
+        ...(configs.document?.fieldMappings ?? {}),
+    };
+    const entities = entityOrder.flatMap((key) => entityMap.get(key) ?? []);
+    const hasFieldMappings = Object.keys(fieldMappings).length > 0;
+    // Page structure: each setting from the most specific scope that gives it
+    const structure = {
+        ...configs.collection?.structure,
+        ...configs.route?.structure,
+        ...configs.document?.structure,
+    };
+    const hasStructure = Object.keys(structure).length > 0;
+    return {
+        entities,
+        ...(hasFieldMappings ? { fieldMappings } : {}),
+        ...(hasStructure ? { structure } : {}),
+    };
+}
+//# sourceMappingURL=effective-config.js.map

package/dist/graph/effective-config.js.map

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

package/dist/graph/id-conventions.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Entity @id conventions for Schema.org @graph linking.
+ *
+ * IDs follow a predictable pattern so entities can cross-reference
+ * each other within the same @graph block.
+ *
+ * Naming convention for the URL fragment:
+ * - Site-level entities use a short, distinctive lowercased name keyed off
+ *   the entity's role: `#business`, `#website`, `#person`.
+ * - Document-level entities use the lowercased Schema.org type with any
+ *   structural suffix dropped:
+ *   - `BreadcrumbList` → `#breadcrumb` (drops `List`)
+ *   - `FAQPage`        → `#faq`        (drops `Page`)
+ *   - `VideoObject`    → `#video`      (drops `Object`)
+ * - Schema.org types without a structural suffix use the full lowercased
+ *   name: `#article`, `#event`, `#recipe`, `#howto`, `#course`, `#jobposting`.
+ *
+ * The reason for the asymmetry: short names are more readable in JSON-LD
+ * cross-references, but only some Schema.org types have a redundant suffix
+ * that can be dropped without ambiguity. Types like `JobPosting` and
+ * `LocalBusiness` would lose meaning if shortened.
+ *
+ * The fragments are URL components, not Schema.org type names — they only
+ * need to be unique within a single @graph block. Consumers of the JSON-LD
+ * output should not rely on the fragment matching the type name.
+ */
+/**
+ * Build a document @id from base URL, path, and fragment: the page's URL with
+ * one trailing slash, then the fragment — the home page (`/`) and the site
+ * (`''`) both read `https://example.com/#…`
+ */
+export declare function documentId(baseUrl: string, path: string, fragment: string): string;
+export declare function businessId(baseUrl: string): string;
+export declare function websiteId(baseUrl: string): string;
+export declare function personId(baseUrl: string): string;
+export declare function articleId(baseUrl: string, path: string): string;
+export declare function breadcrumbId(baseUrl: string, path: string): string;
+export declare function faqId(baseUrl: string, path: string): string;
+export declare function eventId(baseUrl: string, path: string): string;
+export declare function recipeId(baseUrl: string, path: string): string;
+export declare function howToId(baseUrl: string, path: string): string;
+export declare function courseId(baseUrl: string, path: string): string;
+export declare function jobPostingId(baseUrl: string, path: string): string;
+export declare function videoObjectId(baseUrl: string, path: string): string;
+export declare function serviceId(baseUrl: string, path: string): string;
+export declare function productId(baseUrl: string, path: string): string;
+//# sourceMappingURL=id-conventions.d.ts.map

package/dist/graph/id-conventions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-conventions.d.ts","sourceRoot":"","sources":["../../src/graph/id-conventions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGlF;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAElE;AAED,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAElE;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/D"}

package/dist/graph/id-conventions.js

@@ -0,0 +1,78 @@
+/**
+ * Entity @id conventions for Schema.org @graph linking.
+ *
+ * IDs follow a predictable pattern so entities can cross-reference
+ * each other within the same @graph block.
+ *
+ * Naming convention for the URL fragment:
+ * - Site-level entities use a short, distinctive lowercased name keyed off
+ *   the entity's role: `#business`, `#website`, `#person`.
+ * - Document-level entities use the lowercased Schema.org type with any
+ *   structural suffix dropped:
+ *   - `BreadcrumbList` → `#breadcrumb` (drops `List`)
+ *   - `FAQPage`        → `#faq`        (drops `Page`)
+ *   - `VideoObject`    → `#video`      (drops `Object`)
+ * - Schema.org types without a structural suffix use the full lowercased
+ *   name: `#article`, `#event`, `#recipe`, `#howto`, `#course`, `#jobposting`.
+ *
+ * The reason for the asymmetry: short names are more readable in JSON-LD
+ * cross-references, but only some Schema.org types have a redundant suffix
+ * that can be dropped without ambiguity. Types like `JobPosting` and
+ * `LocalBusiness` would lose meaning if shortened.
+ *
+ * The fragments are URL components, not Schema.org type names — they only
+ * need to be unique within a single @graph block. Consumers of the JSON-LD
+ * output should not rely on the fragment matching the type name.
+ */
+/**
+ * Build a document @id from base URL, path, and fragment: the page's URL with
+ * one trailing slash, then the fragment — the home page (`/`) and the site
+ * (`''`) both read `https://example.com/#…`
+ */
+export function documentId(baseUrl, path, fragment) {
+    const page = `${baseUrl.replace(/\/+$/, '')}${path.replace(/\/+$/, '')}`;
+    return `${page}/#${fragment}`;
+}
+export function businessId(baseUrl) {
+    return documentId(baseUrl, '', 'business');
+}
+export function websiteId(baseUrl) {
+    return documentId(baseUrl, '', 'website');
+}
+export function personId(baseUrl) {
+    return documentId(baseUrl, '', 'person');
+}
+export function articleId(baseUrl, path) {
+    return documentId(baseUrl, path, 'article');
+}
+export function breadcrumbId(baseUrl, path) {
+    return documentId(baseUrl, path, 'breadcrumb');
+}
+export function faqId(baseUrl, path) {
+    return documentId(baseUrl, path, 'faq');
+}
+export function eventId(baseUrl, path) {
+    return documentId(baseUrl, path, 'event');
+}
+export function recipeId(baseUrl, path) {
+    return documentId(baseUrl, path, 'recipe');
+}
+export function howToId(baseUrl, path) {
+    return documentId(baseUrl, path, 'howto');
+}
+export function courseId(baseUrl, path) {
+    return documentId(baseUrl, path, 'course');
+}
+export function jobPostingId(baseUrl, path) {
+    return documentId(baseUrl, path, 'jobposting');
+}
+export function videoObjectId(baseUrl, path) {
+    return documentId(baseUrl, path, 'video');
+}
+export function serviceId(baseUrl, path) {
+    return documentId(baseUrl, path, 'service');
+}
+export function productId(baseUrl, path) {
+    return documentId(baseUrl, path, 'product');
+}
+//# sourceMappingURL=id-conventions.js.map

package/dist/graph/id-conventions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-conventions.js","sourceRoot":"","sources":["../../src/graph/id-conventions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,OAAe,EAAE,IAAY,EAAE,QAAgB;IACxE,MAAM,IAAI,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,EAAE,CAAA;IACxE,OAAO,GAAG,IAAI,KAAK,QAAQ,EAAE,CAAA;AAC/B,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,OAAO,UAAU,CAAC,OAAO,EAAE,EAAE,EAAE,UAAU,CAAC,CAAA;AAC5C,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,OAAe;IACvC,OAAO,UAAU,CAAC,OAAO,EAAE,EAAE,EAAE,SAAS,CAAC,CAAA;AAC3C,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,OAAe;IACtC,OAAO,UAAU,CAAC,OAAO,EAAE,EAAE,EAAE,QAAQ,CAAC,CAAA;AAC1C,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,OAAe,EAAE,IAAY;IACrD,OAAO,UAAU,CAAC,OAAO,EAAE,IAAI,EAAE,SAAS,CAAC,CAAA;AAC7C,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,IAAY;IACxD,OAAO,UAAU,CAAC,OAAO,EAAE,IAAI,EAAE,YAAY,CAAC,CAAA;AAChD,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,OAAe,EAAE,IAAY;IACjD,OAAO,UAAU,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,CAAA;AACzC,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,OAAe,EAAE,IAAY;IACnD,OAAO,UAAU,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,CAAA;AAC3C,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,OAAe,EAAE,IAAY;IACpD,OAAO,UAAU,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAA;AAC5C,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,OAAe,EAAE,IAAY;IACnD,OAAO,UAAU,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,CAAA;AAC3C,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,OAAe,EAAE,IAAY;IACpD,OAAO,UAAU,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAA;AAC5C,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,IAAY;IACxD,OAAO,UAAU,CAAC,OAAO,EAAE,IAAI,EAAE,YAAY,CAAC,CAAA;AAChD,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAAe,EAAE,IAAY;IACzD,OAAO,UAAU,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,CAAA;AAC3C,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,OAAe,EAAE,IAAY;IACrD,OAAO,UAAU,CAAC,OAAO,EAAE,IAAI,EAAE,SAAS,CAAC,CAAA;AAC7C,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,OAAe,EAAE,IAAY;IACrD,OAAO,UAAU,CAAC,OAAO,EAAE,IAAI,EAAE,SAAS,CAAC,CAAA;AAC7C,CAAC"}