pub fn materialize(
target: &mut Document,
packs: &[LibraryPack],
pkg_id: &str,
item: &str,
page_id: &str,
id_base: &str,
at: (f64, f64),
) -> Result<AddOutcome, AddError>Expand description
Materialize the pack item pkg_id#item into target at (at_x, at_y) on the
page page_id, returning the AddOutcome describing what was added.
This is the PURE core of library add: it mutates the parsed target
Document in place and performs NO filesystem or process I/O (the caller
resolves the pack set, reads files, formats, and writes). Steps:
- Resolve the FIRST pack in
packswhose id ==pkg_id(project shadows preset); load its fullDocumentand find theComponentDef==item. - Copy that component into
targetunder a namespaced id (lib.<sanitized-pkg>.<item>), REUSING an existing copy if present (dedup). Child ids are left untouched (instance expansion prefixes them at compile). - Copy ALL of the pack’s tokens/styles/assets into
target, deduping by id; a same-id-but-different-definition collision keeps the target’s existing one and records alibrary.dependency_conflictwarning. - Generate a unique instance id (base =
id_base) against ALL target ids, insert anInstanceNodereferencing the copied component onto the page. - Record a
librariesentry forpkg_id(if absent) and a uniqueprovenancerecord linking the instance to the item.
§Errors
Returns AddError when the package or item is unknown (the message lists
the available options), or the page id is not found.