.bbart art libraries
User-managed reusable-artwork collections. JSON-based, content-deduplicated, self-contained.
A .bbart file is a collection of artwork clips you want to reuse across projects: logos, decorations, common shapes, captured selections. The Art Library panel loads and edits them.
Unlike .lzrproj projects (which represent a single in-progress design), .bbart files are organized libraries, designed for sharing, version control, and reuse.
What it contains
| Field | Notes |
|---|---|
library_id | UUID. Identifies the library uniquely (not by file name). |
name | Display name. Editable. |
items[] | Each item has its own id, kind, geometry, thumbnails, tags, category. |
Item kinds
- External file: references a source image or vector file. The item carries the original bytes (deduplicated by content hash within the library).
- Selection snapshot: a flattened version of a selection captured from a project. Text is flattened to geometry, no font dependency for the recipient. Includes
source_text_metadatafor future re-authoring.
Thumbnails
Each item has a frontend-generated thumbnail bundled into the file. No live render needed when loading the library.
Deduplication
Within a single .bbart file, identical raster bytes (by content hash) are stored once and referenced from multiple items. Reduces file size when you re-import the same image as multiple items.
How to read and write
- GUI: the Art Library panel creates, loads, saves, imports, exports.
- CLI: currently not exposed.
A .bbart file is opened by Beam Bench and stays in memory while edited. Write-through persistence: every mutating action writes through to disk immediately. If the disk write fails, the in-memory mutation is kept and the library gets a save_error, and destructive operations are blocked until retry.
Migration from legacy JSON
Legacy app-data *.json libraries auto-migrate to sibling .bbart files on first launch. The original .json is left in place.
Sharing libraries
A .bbart file is portable. Email or upload it; the recipient opens with the Art Library panel → Load.
If two .bbart files share the same library_id (e.g. you copied one), the second one to load gets remapped, a new id is minted, the file rewritten, and a warning surfaces. This prevents id collisions silently.
Edge cases
- Saving fails (file permissions, locked file, full disk), the library shows a save error and disables destructive operations until the next save succeeds. State is not silently rolled back.
- Renaming a
.bbartfile on disk only changes the display name. Thelibrary_idand contents are intact. - The same display name on two files is fine as long as their
library_iddiffers.