@jdevalk/seo-graph-core 0.4.1 → 0.5.0

package/README.md

@@ -46,16 +46,16 @@ object with `@type` and `@id`. Builders for CreativeWork subtypes (`WebSite`,
 | `buildWebSite`               | `WebSite`               | —                                                                                                          |
 | `buildWebPage`               | `WebPage`               | `'WebPage'` \| `'ProfilePage'` \| `'CollectionPage'`                                                       |
 | `buildArticle`               | `Article`               | `'Article'` \| `'BlogPosting'` \| `'NewsArticle'` \| `'TechArticle'` \| `'ScholarlyArticle'` \| `'Report'` |
-| `buildPerson`                | `Person`                | —                                                                                                          |
-| `buildOrganization`          | `Organization`          | Any subtype string (e.g. `'Restaurant'`, `'LocalBusiness'`)                                                |
 | `buildBreadcrumbList`        | `BreadcrumbList`        | —                                                                                                          |
 | `buildImageObject`           | `ImageObject`           | —                                                                                                          |
 | `buildVideoObject`           | `VideoObject`           | —                                                                                                          |
 | `buildSiteNavigationElement` | `SiteNavigationElement` | —                                                                                                          |
-| `buildCustomPiece`           | Any                     | Pass `@type` directly in the input object                                                                  |
+| `buildPiece`                 | Any                     | `schema-dts` generic for autocomplete (e.g. `buildPiece<Product>`, `buildPiece<Person>`)                   |
 
-Every builder accepts an `extra` escape hatch for schema.org properties not
-covered by the typed interface.
+All schema.org properties are accepted at the top level with full autocomplete
+from `schema-dts`. Dedicated builders handle ID generation, date conversion,
+and non-trivial transforms. Use `buildPiece<Type>` for everything else
+(Person, Organization, Blog, Product, Recipe, Event, etc.).
 
 ## Usage
 

package/dist/assemble.d.ts

@@ -1,9 +1,24 @@
 import type { GraphEntity } from './types.js';
+export interface AssembleGraphOptions {
+    /**
+     * When `true`, logs a warning for every `{ '@id': '...' }` reference
+     * in the graph that doesn't resolve to an entity with a matching
+     * `@id`. Helps catch broken links in the graph (e.g. a WebSite
+     * referencing a Person that was never included).
+     *
+     * Defaults to `false`.
+     */
+    warnOnDanglingReferences?: boolean;
+}
 /**
  * Wrap a list of pieces in a `@context + @graph` envelope. Pieces are
  * deduplicated by `@id` before assembly; first occurrence wins.
+ *
+ * When `warnOnDanglingReferences` is enabled, logs warnings for any
+ * `{ '@id': '...' }` reference that doesn't resolve to an entity in
+ * the graph.
  */
-export declare function assembleGraph<T extends GraphEntity>(pieces: readonly T[]): {
+export declare function assembleGraph<T extends GraphEntity>(pieces: readonly T[], options?: AssembleGraphOptions): {
     '@context': 'https://schema.org';
     '@graph': T[];
 };

package/dist/assemble.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assemble.d.ts","sourceRoot":"","sources":["../src/assemble.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG9C;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,WAAW,EAC/C,MAAM,EAAE,SAAS,CAAC,EAAE,GACrB;IAAE,UAAU,EAAE,oBAAoB,CAAC;IAAC,QAAQ,EAAE,CAAC,EAAE,CAAA;CAAE,CAKrD"}
+{"version":3,"file":"assemble.d.ts","sourceRoot":"","sources":["../src/assemble.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG9C,MAAM,WAAW,oBAAoB;IACjC;;;;;;;OAOG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACtC;AA8BD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,WAAW,EAC/C,MAAM,EAAE,SAAS,CAAC,EAAE,EACpB,OAAO,CAAC,EAAE,oBAAoB,GAC/B;IAAE,UAAU,EAAE,oBAAoB,CAAC;IAAC,QAAQ,EAAE,CAAC,EAAE,CAAA;CAAE,CAsCrD"}

package/dist/assemble.js

@@ -1,12 +1,69 @@
 import { deduplicateByGraphId } from './dedupe.js';
+/**
+ * Walk a value recursively and collect every `{ '@id': string }` reference
+ * that is NOT a top-level entity (i.e. doesn't have `@type`).
+ */
+function collectReferences(value, refs) {
+    if (value === null || value === undefined || typeof value !== 'object')
+        return;
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            collectReferences(item, refs);
+        }
+        return;
+    }
+    const obj = value;
+    // An object with @id but no @type is a reference, not an entity.
+    if (typeof obj['@id'] === 'string' && obj['@type'] === undefined) {
+        refs.add(obj['@id']);
+        return;
+    }
+    // Recurse into values of entities/nested objects.
+    for (const val of Object.values(obj)) {
+        collectReferences(val, refs);
+    }
+}
 /**
  * Wrap a list of pieces in a `@context + @graph` envelope. Pieces are
  * deduplicated by `@id` before assembly; first occurrence wins.
+ *
+ * When `warnOnDanglingReferences` is enabled, logs warnings for any
+ * `{ '@id': '...' }` reference that doesn't resolve to an entity in
+ * the graph.
  */
-export function assembleGraph(pieces) {
+export function assembleGraph(pieces, options) {
+    const graph = deduplicateByGraphId(pieces);
+    if (options?.warnOnDanglingReferences) {
+        const entityIds = new Set();
+        for (const entity of graph) {
+            if (typeof entity['@id'] === 'string') {
+                entityIds.add(entity['@id']);
+            }
+        }
+        // Map from referenced @id → @type of the entity that references it.
+        const refs = new Map();
+        for (const entity of graph) {
+            const sourceType = String(entity['@type']);
+            const collected = new Set();
+            for (const [key, val] of Object.entries(entity)) {
+                if (key === '@id')
+                    continue;
+                collectReferences(val, collected);
+            }
+            for (const ref of collected) {
+                if (!refs.has(ref))
+                    refs.set(ref, sourceType);
+            }
+        }
+        for (const [ref, sourceType] of refs) {
+            if (!entityIds.has(ref)) {
+                console.warn(`[seo-graph] Dangling reference in ${sourceType}: { "@id": "${ref}" } does not match any entity in the graph.`);
+            }
+        }
+    }
     return {
         '@context': 'https://schema.org',
-        '@graph': deduplicateByGraphId(pieces),
+        '@graph': graph,
     };
 }
 //# sourceMappingURL=assemble.js.map

package/dist/assemble.js.map

@@ -1 +1 @@
-{"version":3,"file":"assemble.js","sourceRoot":"","sources":["../src/assemble.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnD;;;GAGG;AACH,MAAM,UAAU,aAAa,CACzB,MAAoB;IAEpB,OAAO;QACH,UAAU,EAAE,oBAAoB;QAChC,QAAQ,EAAE,oBAAoB,CAAC,MAAM,CAAC;KACzC,CAAC;AACN,CAAC"}
+{"version":3,"file":"assemble.js","sourceRoot":"","sources":["../src/assemble.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAcnD;;;GAGG;AACH,SAAS,iBAAiB,CAAC,KAAc,EAAE,IAAiB;IACxD,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO;IAE/E,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACvB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACvB,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAClC,CAAC;QACD,OAAO;IACX,CAAC;IAED,MAAM,GAAG,GAAG,KAAgC,CAAC;IAE7C,iEAAiE;IACjE,IAAI,OAAO,GAAG,CAAC,KAAK,CAAC,KAAK,QAAQ,IAAI,GAAG,CAAC,OAAO,CAAC,KAAK,SAAS,EAAE,CAAC;QAC/D,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;QACrB,OAAO;IACX,CAAC;IAED,kDAAkD;IAClD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;QACnC,iBAAiB,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACjC,CAAC;AACL,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CACzB,MAAoB,EACpB,OAA8B;IAE9B,MAAM,KAAK,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAE3C,IAAI,OAAO,EAAE,wBAAwB,EAAE,CAAC;QACpC,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAC;QACpC,KAAK,MAAM,MAAM,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,OAAO,MAAM,CAAC,KAAK,CAAC,KAAK,QAAQ,EAAE,CAAC;gBACpC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YACjC,CAAC;QACL,CAAC;QAED,oEAAoE;QACpE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAC;QACvC,KAAK,MAAM,MAAM,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;YAC3C,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAC;YACpC,KAAK,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC9C,IAAI,GAAG,KAAK,KAAK;oBAAE,SAAS;gBAC5B,iBAAiB,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;YACtC,CAAC;YACD,KAAK,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;gBAC1B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;oBAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;YAClD,CAAC;QACL,CAAC;QAED,KAAK,MAAM,CAAC,GAAG,EAAE,UAAU,CAAC,IAAI,IAAI,EAAE,CAAC;YACnC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBACtB,OAAO,CAAC,IAAI,CACR,qCAAqC,UAAU,eAAe,GAAG,6CAA6C,CACjH,CAAC;YACN,CAAC;QACL,CAAC;IACL,CAAC;IAED,OAAO;QACH,UAAU,EAAE,oBAAoB;QAChC,QAAQ,EAAE,KAAK;KAClB,CAAC;AACN,CAAC"}

package/dist/index.d.ts

@@ -1,15 +1,12 @@
 export type { GraphEntity, Reference, SchemaGraph, CreativeWorkFields } from './types.js';
-export { applyCreativeWorkFields } from './types.js';
+export { applyCreativeWorkFields, spreadRemainingProperties, CREATIVE_WORK_KEYS } from './types.js';
 export type { IdFactory, MakeIdsOptions } from './ids.js';
 export { makeIds } from './ids.js';
 export { deduplicateByGraphId } from './dedupe.js';
 export { assembleGraph } from './assemble.js';
+export type { AssembleGraphOptions } from './assemble.js';
 export { buildWebSite } from './pieces/website.js';
 export type { WebSiteInput } from './pieces/website.js';
-export { buildPerson } from './pieces/person.js';
-export type { PersonInput } from './pieces/person.js';
-export { buildOrganization } from './pieces/organization.js';
-export type { OrganizationInput } from './pieces/organization.js';
 export { buildSiteNavigationElement } from './pieces/navigation.js';
 export type { NavigationItem, SiteNavigationInput } from './pieces/navigation.js';
 export { buildWebPage } from './pieces/webpage.js';
@@ -22,5 +19,5 @@ export { buildImageObject } from './pieces/image.js';
 export type { ImageObjectInput } from './pieces/image.js';
 export { buildVideoObject } from './pieces/video.js';
 export type { VideoObjectInput } from './pieces/video.js';
-export { buildCustomPiece } from './pieces/custom.js';
+export { buildPiece } from './pieces/custom.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC1F,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AACrD,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC1D,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAG9C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,YAAY,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE,OAAO,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AACpE,YAAY,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElF,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAErE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAErE,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,YAAY,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElF,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,YAAY,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,YAAY,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC1F,OAAO,EAAE,uBAAuB,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACpG,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC1D,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,YAAY,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAG1D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AACpE,YAAY,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElF,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAErE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAErE,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,YAAY,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElF,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,YAAY,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,YAAY,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -1,17 +1,15 @@
 // @jdevalk/seo-graph-core — agent-ready schema.org JSON-LD graph builders.
-export { applyCreativeWorkFields } from './types.js';
+export { applyCreativeWorkFields, spreadRemainingProperties, CREATIVE_WORK_KEYS } from './types.js';
 export { makeIds } from './ids.js';
 export { deduplicateByGraphId } from './dedupe.js';
 export { assembleGraph } from './assemble.js';
 // Piece builders
 export { buildWebSite } from './pieces/website.js';
-export { buildPerson } from './pieces/person.js';
-export { buildOrganization } from './pieces/organization.js';
 export { buildSiteNavigationElement } from './pieces/navigation.js';
 export { buildWebPage } from './pieces/webpage.js';
 export { buildArticle } from './pieces/article.js';
 export { buildBreadcrumbList } from './pieces/breadcrumb.js';
 export { buildImageObject } from './pieces/image.js';
 export { buildVideoObject } from './pieces/video.js';
-export { buildCustomPiece } from './pieces/custom.js';
+export { buildPiece } from './pieces/custom.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAG3E,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAErD,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE9C,iBAAiB;AACjB,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAG7D,OAAO,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AAGpE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAG7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAGrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAGrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAG3E,OAAO,EAAE,uBAAuB,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEpG,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAG9C,iBAAiB;AACjB,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD,OAAO,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AAGpE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAG7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAGrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAGrD,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/pieces/article.d.ts

@@ -1,6 +1,14 @@
+import type { ArticleLeaf } from 'schema-dts';
 import type { IdFactory } from '../ids.js';
 import type { Reference, CreativeWorkFields } from '../types.js';
-export interface ArticleInput extends CreativeWorkFields {
+/**
+ * Concrete Article subtype. `Article` is the default; use `BlogPosting`
+ * for blog posts, `NewsArticle` for journalism, `TechArticle` for
+ * technical docs, `ScholarlyArticle` for academic papers, or `Report`
+ * for data/research reports.
+ */
+export type ArticleType = 'Article' | 'BlogPosting' | 'NewsArticle' | 'TechArticle' | 'ScholarlyArticle' | 'Report';
+interface ArticleCoreFields extends CreativeWorkFields {
     /** Canonical URL of the article's page. The @id is `${url}#article`. */
     url: string;
     /** Reference to the enclosing WebPage (usually ids.webPage(url)). */
@@ -19,25 +27,12 @@ export interface ArticleInput extends CreativeWorkFields {
     /** Top-level category, emitted as `articleSection`. */
     articleSection?: string;
     wordCount?: number;
-    /**
-     * Full or truncated article body, emitted as `articleBody`. Pass from
-     * the aggregator / build step; core doesn't derive it from anything.
-     */
     articleBody?: string;
-    extra?: Record<string, unknown>;
 }
+export type ArticleInput = ArticleCoreFields & Omit<Partial<ArticleLeaf>, keyof ArticleCoreFields | '@type'>;
 /**
- * Concrete Article subtype. `Article` is the default; use `BlogPosting`
- * for blog posts, `NewsArticle` for journalism, `TechArticle` for
- * technical docs, `ScholarlyArticle` for academic papers, or `Report`
- * for data/research reports.
- */
-export type ArticleType = 'Article' | 'BlogPosting' | 'NewsArticle' | 'TechArticle' | 'ScholarlyArticle' | 'Report';
-/**
- * Build a schema.org Article piece. The caller is responsible for pre-
- * computing the references (author, publisher, isPartOf, image) using the
- * IdFactory, so core doesn't have to know anything about how the site
- * models its Person/Organization/WebPage entities.
+ * Build a schema.org Article piece.
  */
 export declare function buildArticle(input: ArticleInput, ids: IdFactory, type?: ArticleType): Record<string, unknown>;
+export {};
 //# sourceMappingURL=article.d.ts.map

package/dist/pieces/article.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"article.d.ts","sourceRoot":"","sources":["../../src/pieces/article.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjE,MAAM,WAAW,YAAa,SAAQ,kBAAkB;IACpD,wEAAwE;IACxE,GAAG,EAAE,MAAM,CAAC;IACZ,qEAAqE;IACrE,QAAQ,EAAE,SAAS,CAAC;IACpB,kEAAkE;IAClE,MAAM,EAAE,SAAS,CAAC;IAClB,8EAA8E;IAC9E,SAAS,EAAE,SAAS,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC;IACpB,6FAA6F;IAC7F,aAAa,EAAE,IAAI,CAAC;IACpB,oDAAoD;IACpD,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,uDAAuD;IACvD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GACjB,SAAS,GACT,aAAa,GACb,aAAa,GACb,aAAa,GACb,kBAAkB,GAClB,QAAQ,CAAC;AAEf;;;;;GAKG;AACH,wBAAgB,YAAY,CACxB,KAAK,EAAE,YAAY,EACnB,GAAG,EAAE,SAAS,EACd,IAAI,GAAE,WAAuB,GAC9B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAkBzB"}
+{"version":3,"file":"article.d.ts","sourceRoot":"","sources":["../../src/pieces/article.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAOjE;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GACjB,SAAS,GACT,aAAa,GACb,aAAa,GACb,aAAa,GACb,kBAAkB,GAClB,QAAQ,CAAC;AAEf,UAAU,iBAAkB,SAAQ,kBAAkB;IAClD,wEAAwE;IACxE,GAAG,EAAE,MAAM,CAAC;IACZ,qEAAqE;IACrE,QAAQ,EAAE,SAAS,CAAC;IACpB,kEAAkE;IAClE,MAAM,EAAE,SAAS,CAAC;IAClB,8EAA8E;IAC9E,SAAS,EAAE,SAAS,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC;IACpB,6FAA6F;IAC7F,aAAa,EAAE,IAAI,CAAC;IACpB,oDAAoD;IACpD,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,uDAAuD;IACvD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,YAAY,GAAG,iBAAiB,GACxC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,MAAM,iBAAiB,GAAG,OAAO,CAAC,CAAC;AAelE;;GAEG;AACH,wBAAgB,YAAY,CACxB,KAAK,EAAE,YAAY,EACnB,GAAG,EAAE,SAAS,EACd,IAAI,GAAE,WAAuB,GAC9B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAmBzB"}

package/dist/pieces/article.js

@@ -1,9 +1,18 @@
-import { applyCreativeWorkFields } from '../types.js';
+import { applyCreativeWorkFields, spreadRemainingProperties, CREATIVE_WORK_KEYS, } from '../types.js';
+const HANDLED_KEYS = new Set([
+    ...CREATIVE_WORK_KEYS,
+    'url',
+    'isPartOf',
+    'author',
+    'publisher',
+    'headline',
+    'image',
+    'articleSection',
+    'wordCount',
+    'articleBody',
+]);
 /**
- * Build a schema.org Article piece. The caller is responsible for pre-
- * computing the references (author, publisher, isPartOf, image) using the
- * IdFactory, so core doesn't have to know anything about how the site
- * models its Person/Organization/WebPage entities.
+ * Build a schema.org Article piece.
  */
 export function buildArticle(input, ids, type = 'Article') {
     const piece = {
@@ -24,6 +33,7 @@ export function buildArticle(input, ids, type = 'Article') {
         piece.wordCount = input.wordCount;
     if (input.articleBody !== undefined)
         piece.articleBody = input.articleBody;
-    return { ...piece, ...input.extra };
+    spreadRemainingProperties(piece, input, HANDLED_KEYS);
+    return piece;
 }
 //# sourceMappingURL=article.js.map

package/dist/pieces/article.js.map

@@ -1 +1 @@
-{"version":3,"file":"article.js","sourceRoot":"","sources":["../../src/pieces/article.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AA2CtD;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CACxB,KAAmB,EACnB,GAAc,EACd,OAAoB,SAAS;IAE7B,MAAM,KAAK,GAA4B;QACnC,OAAO,EAAE,IAAI;QACb,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC;QAC7B,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,gBAAgB,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE;QACnD,SAAS,EAAE,KAAK,CAAC,SAAS;KAC7B,CAAC;IAEF,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS;QAAE,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IACzD,uBAAuB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACtC,IAAI,KAAK,CAAC,cAAc,KAAK,SAAS;QAAE,KAAK,CAAC,cAAc,GAAG,KAAK,CAAC,cAAc,CAAC;IACpF,IAAI,KAAK,CAAC,SAAS,KAAK,SAAS;QAAE,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;IACrE,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS;QAAE,KAAK,CAAC,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC;IAE3E,OAAO,EAAE,GAAG,KAAK,EAAE,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC;AACxC,CAAC"}
+{"version":3,"file":"article.js","sourceRoot":"","sources":["../../src/pieces/article.ts"],"names":[],"mappings":"AAIA,OAAO,EACH,uBAAuB,EACvB,yBAAyB,EACzB,kBAAkB,GACrB,MAAM,aAAa,CAAC;AAyCrB,MAAM,YAAY,GAAG,IAAI,GAAG,CAAS;IACjC,GAAG,kBAAkB;IACrB,KAAK;IACL,UAAU;IACV,QAAQ;IACR,WAAW;IACX,UAAU;IACV,OAAO;IACP,gBAAgB;IAChB,WAAW;IACX,aAAa;CAChB,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,UAAU,YAAY,CACxB,KAAmB,EACnB,GAAc,EACd,OAAoB,SAAS;IAE7B,MAAM,KAAK,GAA4B;QACnC,OAAO,EAAE,IAAI;QACb,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC;QAC7B,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,gBAAgB,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE;QACnD,SAAS,EAAE,KAAK,CAAC,SAAS;KAC7B,CAAC;IAEF,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS;QAAE,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IACzD,uBAAuB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACtC,IAAI,KAAK,CAAC,cAAc,KAAK,SAAS;QAAE,KAAK,CAAC,cAAc,GAAG,KAAK,CAAC,cAAc,CAAC;IACpF,IAAI,KAAK,CAAC,SAAS,KAAK,SAAS;QAAE,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;IACrE,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS;QAAE,KAAK,CAAC,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC;IAC3E,yBAAyB,CAAC,KAAK,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;IAEtD,OAAO,KAAK,CAAC;AACjB,CAAC"}

package/dist/pieces/breadcrumb.d.ts

@@ -1,3 +1,4 @@
+import type { BreadcrumbListLeaf } from 'schema-dts';
 import type { IdFactory } from '../ids.js';
 export interface BreadcrumbItem {
     /** Display name for this crumb, e.g. 'Home', 'Blog', 'Open Source'. */
@@ -5,23 +6,16 @@ export interface BreadcrumbItem {
     /** URL for this crumb. */
     url: string;
 }
-export interface BreadcrumbListInput {
-    /**
-     * The URL of the page this breadcrumb belongs to. The @id is
-     * `${url}#breadcrumb`.
-     */
+interface BreadcrumbListCoreFields {
+    /** The URL of the page this breadcrumb belongs to. */
     url: string;
     /** Pre-computed ordered list of crumbs, root first. */
     items: readonly BreadcrumbItem[];
-    extra?: Record<string, unknown>;
 }
+export type BreadcrumbListInput = BreadcrumbListCoreFields & Omit<Partial<BreadcrumbListLeaf>, keyof BreadcrumbListCoreFields | '@type'>;
 /**
  * Build a schema.org BreadcrumbList piece.
- *
- * Breadcrumbs are an input to core, not a derivation. The caller knows
- * its routing conventions; core just wraps the pre-computed items in the
- * right schema.org shape. If you need to derive breadcrumbs from an
- * Astro URL, use `@jdevalk/astro-seo-graph`'s breadcrumb helper instead.
  */
 export declare function buildBreadcrumbList(input: BreadcrumbListInput, ids: IdFactory): Record<string, unknown>;
+export {};
 //# sourceMappingURL=breadcrumb.d.ts.map

package/dist/pieces/breadcrumb.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"breadcrumb.d.ts","sourceRoot":"","sources":["../../src/pieces/breadcrumb.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C,MAAM,WAAW,cAAc;IAC3B,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,GAAG,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAChC;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,uDAAuD;IACvD,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAC/B,KAAK,EAAE,mBAAmB,EAC1B,GAAG,EAAE,SAAS,GACf,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAczB"}
+{"version":3,"file":"breadcrumb.d.ts","sourceRoot":"","sources":["../../src/pieces/breadcrumb.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAG3C,MAAM,WAAW,cAAc;IAC3B,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,GAAG,EAAE,MAAM,CAAC;CACf;AAED,UAAU,wBAAwB;IAC9B,sDAAsD;IACtD,GAAG,EAAE,MAAM,CAAC;IACZ,uDAAuD;IACvD,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;CACpC;AAED,MAAM,MAAM,mBAAmB,GAAG,wBAAwB,GACtD,IAAI,CAAC,OAAO,CAAC,kBAAkB,CAAC,EAAE,MAAM,wBAAwB,GAAG,OAAO,CAAC,CAAC;AAIhF;;GAEG;AACH,wBAAgB,mBAAmB,CAC/B,KAAK,EAAE,mBAAmB,EAC1B,GAAG,EAAE,SAAS,GACf,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAkBzB"}

package/dist/pieces/breadcrumb.js

@@ -1,10 +1,7 @@
+import { spreadRemainingProperties } from '../types.js';
+const HANDLED_KEYS = new Set(['url', 'items']);
 /**
  * Build a schema.org BreadcrumbList piece.
- *
- * Breadcrumbs are an input to core, not a derivation. The caller knows
- * its routing conventions; core just wraps the pre-computed items in the
- * right schema.org shape. If you need to derive breadcrumbs from an
- * Astro URL, use `@jdevalk/astro-seo-graph`'s breadcrumb helper instead.
  */
 export function buildBreadcrumbList(input, ids) {
     const lastIndex = input.items.length - 1;
@@ -14,11 +11,12 @@ export function buildBreadcrumbList(input, ids) {
         name: item.name,
         item: index === lastIndex ? { '@id': ids.webPage(item.url) } : item.url,
     }));
-    return {
+    const piece = {
         '@type': 'BreadcrumbList',
         '@id': ids.breadcrumb(input.url),
         itemListElement,
-        ...input.extra,
     };
+    spreadRemainingProperties(piece, input, HANDLED_KEYS);
+    return piece;
 }
 //# sourceMappingURL=breadcrumb.js.map

package/dist/pieces/breadcrumb.js.map

@@ -1 +1 @@
-{"version":3,"file":"breadcrumb.js","sourceRoot":"","sources":["../../src/pieces/breadcrumb.ts"],"names":[],"mappings":"AAoBA;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAC/B,KAA0B,EAC1B,GAAc;IAEd,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;IACzC,MAAM,eAAe,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;QACtD,OAAO,EAAE,UAAU;QACnB,QAAQ,EAAE,KAAK,GAAG,CAAC;QACnB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,IAAI,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG;KAC1E,CAAC,CAAC,CAAC;IACJ,OAAO;QACH,OAAO,EAAE,gBAAgB;QACzB,KAAK,EAAE,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC;QAChC,eAAe;QACf,GAAG,KAAK,CAAC,KAAK;KACjB,CAAC;AACN,CAAC"}
+{"version":3,"file":"breadcrumb.js","sourceRoot":"","sources":["../../src/pieces/breadcrumb.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAmBxD,MAAM,YAAY,GAAG,IAAI,GAAG,CAAS,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;AAEvD;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAC/B,KAA0B,EAC1B,GAAc;IAEd,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;IACzC,MAAM,eAAe,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;QACtD,OAAO,EAAE,UAAU;QACnB,QAAQ,EAAE,KAAK,GAAG,CAAC;QACnB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,IAAI,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG;KAC1E,CAAC,CAAC,CAAC;IAEJ,MAAM,KAAK,GAA4B;QACnC,OAAO,EAAE,gBAAgB;QACzB,KAAK,EAAE,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC;QAChC,eAAe;KAClB,CAAC;IAEF,yBAAyB,CAAC,KAAK,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;IAEtD,OAAO,KAAK,CAAC;AACjB,CAAC"}

package/dist/pieces/custom.d.ts

@@ -1,12 +1,33 @@
+import type { Thing } from 'schema-dts';
 /**
- * Escape hatch: build an arbitrary schema.org piece from a raw object.
+ * Build an arbitrary schema.org piece from a raw object.
  *
- * Use this when the built-in piece builders don't cover what you need —
- * e.g. a Recipe, Event, Product, or a LocalBusiness subtype that needs
- * a specific shape not captured by `buildOrganization`.
+ * Pass a `schema-dts` type as the generic parameter to get autocomplete.
+ * The `@type` value in your input narrows the union to the matching leaf
+ * type, so `buildPiece<Product>` with `'@type': 'Product'` gives you
+ * full ProductLeaf autocomplete — no need to import Leaf types.
  *
- * Note: the built piece is returned as-is. It's the caller's responsibility
- * to supply a valid `@type` and (if cross-referenced) a stable `@id`.
+ * ```ts
+ * import type { Product } from 'schema-dts';
+ * buildPiece<Product>({
+ *     '@type': 'Product',
+ *     '@id': `${url}#product`,
+ *     name: 'Running Shoe',
+ *     color: 'Black',           // ← autocomplete from schema-dts
+ *     sku: 'ABC123',            // ← autocomplete from schema-dts
+ * });
+ * ```
+ *
+ * Without a generic, the input is untyped — any properties are accepted.
  */
-export declare function buildCustomPiece<T extends Record<string, unknown>>(raw: T): T;
+export declare function buildPiece<T extends Thing, TType extends string = string>(raw: Partial<Extract<T, {
+    '@type': TType;
+}>> & {
+    '@type': TType;
+    '@id'?: string;
+}): Record<string, unknown>;
+export declare function buildPiece(raw: Record<string, unknown> & {
+    '@type': string | readonly string[];
+    '@id'?: string;
+}): Record<string, unknown>;
 //# sourceMappingURL=custom.d.ts.map

package/dist/pieces/custom.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"custom.d.ts","sourceRoot":"","sources":["../../src/pieces/custom.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAE7E"}
+{"version":3,"file":"custom.d.ts","sourceRoot":"","sources":["../../src/pieces/custom.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,KAAK,EAAE,KAAK,SAAS,MAAM,GAAG,MAAM,EACrE,GAAG,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,EAAE;IAAE,OAAO,EAAE,KAAK,CAAA;CAAE,CAAC,CAAC,GAAG;IAC3C,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB,GACF,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC3B,wBAAgB,UAAU,CACtB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAC3B,OAAO,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB,GACF,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC"}

package/dist/pieces/custom.js

@@ -1,14 +1,4 @@
-/**
- * Escape hatch: build an arbitrary schema.org piece from a raw object.
- *
- * Use this when the built-in piece builders don't cover what you need —
- * e.g. a Recipe, Event, Product, or a LocalBusiness subtype that needs
- * a specific shape not captured by `buildOrganization`.
- *
- * Note: the built piece is returned as-is. It's the caller's responsibility
- * to supply a valid `@type` and (if cross-referenced) a stable `@id`.
- */
-export function buildCustomPiece(raw) {
+export function buildPiece(raw) {
     return raw;
 }
 //# sourceMappingURL=custom.js.map

package/dist/pieces/custom.js.map

@@ -1 +1 @@
-{"version":3,"file":"custom.js","sourceRoot":"","sources":["../../src/pieces/custom.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAoC,GAAM;IACtE,OAAO,GAAG,CAAC;AACf,CAAC"}
+{"version":3,"file":"custom.js","sourceRoot":"","sources":["../../src/pieces/custom.ts"],"names":[],"mappings":"AAmCA,MAAM,UAAU,UAAU,CAAC,GAA4B;IACnD,OAAO,GAAG,CAAC;AACf,CAAC"}

package/dist/pieces/image.d.ts

@@ -1,12 +1,7 @@
+import type { ImageObjectLeaf } from 'schema-dts';
 import type { IdFactory } from '../ids.js';
-export interface ImageObjectInput {
-    /**
-     * Canonical URL of the page this image belongs to. The @id is
-     * `${pageUrl}#primaryimage` — to build a site-wide image with a
-     * friendly fragment (e.g. the Person logo), use the `id` override.
-     */
+interface ImageObjectCoreFields {
     pageUrl?: string;
-    /** Explicit @id override; takes precedence over `pageUrl`. */
     id?: string;
     /** Public URL of the image file. Used for both `url` and `contentUrl`. */
     url: string;
@@ -14,12 +9,13 @@ export interface ImageObjectInput {
     height: number;
     inLanguage?: string;
     caption?: string;
-    extra?: Record<string, unknown>;
 }
+export type ImageObjectInput = ImageObjectCoreFields & Omit<Partial<ImageObjectLeaf>, keyof ImageObjectCoreFields | '@type'>;
 /**
  * Build a schema.org ImageObject piece. Pass `pageUrl` for a page's
  * primary image (id = `${pageUrl}#primaryimage`), or `id` for a site-
  * wide image like a personal logo.
  */
 export declare function buildImageObject(input: ImageObjectInput, ids: IdFactory): Record<string, unknown>;
+export {};
 //# sourceMappingURL=image.d.ts.map

package/dist/pieces/image.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../../src/pieces/image.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C,MAAM,WAAW,gBAAgB;IAC7B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,gBAAgB,EAAE,GAAG,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAmBjG"}
+{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../../src/pieces/image.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAG3C,UAAU,qBAAqB;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,gBAAgB,GAAG,qBAAqB,GAChD,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,EAAE,MAAM,qBAAqB,GAAG,OAAO,CAAC,CAAC;AAY1E;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,gBAAgB,EAAE,GAAG,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAoBjG"}

package/dist/pieces/image.js

@@ -1,16 +1,26 @@
+import { spreadRemainingProperties } from '../types.js';
+const HANDLED_KEYS = new Set([
+    'pageUrl',
+    'id',
+    'url',
+    'width',
+    'height',
+    'inLanguage',
+    'caption',
+]);
 /**
  * Build a schema.org ImageObject piece. Pass `pageUrl` for a page's
  * primary image (id = `${pageUrl}#primaryimage`), or `id` for a site-
  * wide image like a personal logo.
  */
 export function buildImageObject(input, ids) {
-    const id = input.id ?? (input.pageUrl !== undefined ? ids.primaryImage(input.pageUrl) : undefined);
-    if (id === undefined) {
+    const resolvedId = input.id ?? (input.pageUrl !== undefined ? ids.primaryImage(input.pageUrl) : undefined);
+    if (resolvedId === undefined) {
         throw new Error('buildImageObject: either `id` or `pageUrl` is required');
     }
     const piece = {
         '@type': 'ImageObject',
-        '@id': id,
+        '@id': resolvedId,
         url: input.url,
         contentUrl: input.url,
         width: input.width,
@@ -20,6 +30,7 @@ export function buildImageObject(input, ids) {
         piece.caption = input.caption;
     if (input.inLanguage !== undefined)
         piece.inLanguage = input.inLanguage;
-    return { ...piece, ...input.extra };
+    spreadRemainingProperties(piece, input, HANDLED_KEYS);
+    return piece;
 }
 //# sourceMappingURL=image.js.map

package/dist/pieces/image.js.map

@@ -1 +1 @@
-{"version":3,"file":"image.js","sourceRoot":"","sources":["../../src/pieces/image.ts"],"names":[],"mappings":"AAoBA;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAuB,EAAE,GAAc;IACpE,MAAM,EAAE,GACJ,KAAK,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAC5F,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC9E,CAAC;IAED,MAAM,KAAK,GAA4B;QACnC,OAAO,EAAE,aAAa;QACtB,KAAK,EAAE,EAAE;QACT,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,UAAU,EAAE,KAAK,CAAC,GAAG;QACrB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,MAAM,EAAE,KAAK,CAAC,MAAM;KACvB,CAAC;IACF,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS;QAAE,KAAK,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC/D,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS;QAAE,KAAK,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC;IAExE,OAAO,EAAE,GAAG,KAAK,EAAE,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC;AACxC,CAAC"}
+{"version":3,"file":"image.js","sourceRoot":"","sources":["../../src/pieces/image.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAgBxD,MAAM,YAAY,GAAG,IAAI,GAAG,CAAS;IACjC,SAAS;IACT,IAAI;IACJ,KAAK;IACL,OAAO;IACP,QAAQ;IACR,YAAY;IACZ,SAAS;CACZ,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAuB,EAAE,GAAc;IACpE,MAAM,UAAU,GACZ,KAAK,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAC5F,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC9E,CAAC;IAED,MAAM,KAAK,GAA4B;QACnC,OAAO,EAAE,aAAa;QACtB,KAAK,EAAE,UAAU;QACjB,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,UAAU,EAAE,KAAK,CAAC,GAAG;QACrB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,MAAM,EAAE,KAAK,CAAC,MAAM;KACvB,CAAC;IACF,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS;QAAE,KAAK,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC/D,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS;QAAE,KAAK,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC;IACxE,yBAAyB,CAAC,KAAK,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;IAEtD,OAAO,KAAK,CAAC;AACjB,CAAC"}

package/dist/pieces/navigation.d.ts

@@ -1,20 +1,20 @@
+import type { SiteNavigationElementLeaf } from 'schema-dts';
 import type { IdFactory } from '../ids.js';
 import type { Reference } from '../types.js';
 export interface NavigationItem {
     name: string;
     url: string;
 }
-export interface SiteNavigationInput {
-    /** Human-readable nav name, e.g. 'Main navigation'. */
+interface SiteNavigationCoreFields {
     name: string;
-    /** Parent WebSite reference (usually ids.website). */
     isPartOf: Reference;
     items: readonly NavigationItem[];
-    extra?: Record<string, unknown>;
 }
+export type SiteNavigationInput = SiteNavigationCoreFields & Omit<Partial<SiteNavigationElementLeaf>, keyof SiteNavigationCoreFields | '@type'>;
 /**
  * Build a schema.org SiteNavigationElement whose `hasPart` is a list of
  * sub-SiteNavigationElement entries (one per nav link).
  */
 export declare function buildSiteNavigationElement(input: SiteNavigationInput, ids: IdFactory): Record<string, unknown>;
+export {};
 //# sourceMappingURL=navigation.d.ts.map

package/dist/pieces/navigation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../src/pieces/navigation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,WAAW,cAAc;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAChC,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,QAAQ,EAAE,SAAS,CAAC;IACpB,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACtC,KAAK,EAAE,mBAAmB,EAC1B,GAAG,EAAE,SAAS,GACf,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAczB"}
+{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../src/pieces/navigation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAE5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAG7C,MAAM,WAAW,cAAc;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACf;AAED,UAAU,wBAAwB;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,SAAS,CAAC;IACpB,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;CACpC;AAED,MAAM,MAAM,mBAAmB,GAAG,wBAAwB,GACtD,IAAI,CAAC,OAAO,CAAC,yBAAyB,CAAC,EAAE,MAAM,wBAAwB,GAAG,OAAO,CAAC,CAAC;AAIvF;;;GAGG;AACH,wBAAgB,0BAA0B,CACtC,KAAK,EAAE,mBAAmB,EAC1B,GAAG,EAAE,SAAS,GACf,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAkBzB"}

package/dist/pieces/navigation.js

@@ -1,3 +1,5 @@
+import { spreadRemainingProperties } from '../types.js';
+const HANDLED_KEYS = new Set(['name', 'isPartOf', 'items']);
 /**
  * Build a schema.org SiteNavigationElement whose `hasPart` is a list of
  * sub-SiteNavigationElement entries (one per nav link).
@@ -8,13 +10,14 @@ export function buildSiteNavigationElement(input, ids) {
         name: item.name,
         url: item.url,
     }));
-    return {
+    const piece = {
         '@type': 'SiteNavigationElement',
         '@id': ids.navigation,
         name: input.name,
         isPartOf: input.isPartOf,
         hasPart,
-        ...input.extra,
     };
+    spreadRemainingProperties(piece, input, HANDLED_KEYS);
+    return piece;
 }
 //# sourceMappingURL=navigation.js.map

package/dist/pieces/navigation.js.map

@@ -1 +1 @@
-{"version":3,"file":"navigation.js","sourceRoot":"","sources":["../../src/pieces/navigation.ts"],"names":[],"mappings":"AAiBA;;;GAGG;AACH,MAAM,UAAU,0BAA0B,CACtC,KAA0B,EAC1B,GAAc;IAEd,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACvC,OAAO,EAAE,uBAAuB;QAChC,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,GAAG,EAAE,IAAI,CAAC,GAAG;KAChB,CAAC,CAAC,CAAC;IACJ,OAAO;QACH,OAAO,EAAE,uBAAuB;QAChC,KAAK,EAAE,GAAG,CAAC,UAAU;QACrB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,OAAO;QACP,GAAG,KAAK,CAAC,KAAK;KACjB,CAAC;AACN,CAAC"}
+{"version":3,"file":"navigation.js","sourceRoot":"","sources":["../../src/pieces/navigation.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAgBxD,MAAM,YAAY,GAAG,IAAI,GAAG,CAAS,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;AAEpE;;;GAGG;AACH,MAAM,UAAU,0BAA0B,CACtC,KAA0B,EAC1B,GAAc;IAEd,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACvC,OAAO,EAAE,uBAAuB;QAChC,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,GAAG,EAAE,IAAI,CAAC,GAAG;KAChB,CAAC,CAAC,CAAC;IAEJ,MAAM,KAAK,GAA4B;QACnC,OAAO,EAAE,uBAAuB;QAChC,KAAK,EAAE,GAAG,CAAC,UAAU;QACrB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,OAAO;KACV,CAAC;IAEF,yBAAyB,CAAC,KAAK,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;IAEtD,OAAO,KAAK,CAAC;AACjB,CAAC"}