Catalog Contract

CatalogSource

A source has:

• a kebab-case id;
• a human-readable label;
• an optional unique prefix;
• sections;
• optional elements.

Final ids are the source prefix plus the local entry id.

CatalogPackage

A package has:

• id and name;
• one or more sources;
• optional version and description;
• optional definitions;
• optional image assets;
• optional templates;
• optional AI instructions and skill pointers.

Use defineCatalog to validate and stamp a package contract.

templates is an array of PageTemplate documents. defineCatalog parses each template and rejects the package when one is malformed. Use exportTemplate to create them so requirements are computed from the actual Page definition.

Element kinds

Kind	Registration
illustration	Registered in a catalog
widget	Registered in a catalog
image	Stored inline with its source URL

Use createCatalog to compose sources and packages into a PageBuilderCatalog.

The returned Catalog exposes:

• packages: summaries with Section, Element, Image, and Template counts;
• sections, illustrations, and elements: registered runtime entries;
• images: package image assets with catalogId provenance;
• templates: templates aggregated from packages in registration order;
• resolveSection, resolveIllustration, and resolveElement: id lookups.

Templates from bare host storage are not added automatically. Concatenate them with catalog.templates when building the current editor surface.

Image asset ids must be unique across composed packages. createCatalog rejects collisions and stamps each image with its package catalogId.

Sections, illustrations, and widgets may set deprecated: true while a host migrates stored content. They remain registered and resolvable by id, but new authoring discovery omits them. canonicalId identifies the current neutral replacement for clipboard migration and other explicit compatibility tools.

Catalog functions

Function	Purpose
defineCatalog(package)	Validate a package and stamp the current catalog contract version
createCatalog(entries)	Compose CatalogSource and CatalogPackage entries into one runtime Catalog
catalogPackageSummary(package)	Return stable Section, Element, Image, and Template counts

See Catalog Templates for the complete template function reference.