@elftia/canvas-core

This package owns the host-neutral canvas artifact vocabulary and pure canvas operations. Its exported declarations are the single public TypeScript contract authority.

The root export also owns the permissive CanvasElement, CanvasAppState, CanvasBinaryFile, and CanvasState scene envelopes. Public consumers never need Elftia's private @elftia/shared package. Host-side runtime validators validate these envelopes and re-export the types instead of redefining them.

The four domain actions are deliberately separate:

• Generation produces a generated asset. Only a true generation result has CanvasGenerationProvenance (runId and outputId).
• Import/store obtains or persists an already available CanvasAsset. It does not place anything on a canvas and does not invent generation provenance.
• Canvas registration uses registerOnCanvas to associate a CanvasRegistrationDraft with a destination canvas and returns a CanvasRegistration containing its element id.
• Pure scene construction uses buildCanvasArtifactSceneContent over CanvasArtifactPlacementInput. It creates byte-free canvas content but performs no persistence itself.

Every placed artifact is identified by its HostArtifactRef in customData.artifactRef. customData.generation is optional and appears only when the caller supplies genuine generation provenance. A local file and a generated output therefore follow the same registration operation without pretending to be the same source action.

React synchronization and presentation live in @elftia/canvas-react. Provider calls, imports, databases, IPC, completion events, caches, and host surface registration remain application concerns outside this package.