Auto-include an attached design system when a page is saved to a library

[codente]

Problem

#517 (commit dd8bee5) exposed the fl_assistant_post_types_known filter so the fl-design-system CPT can appear in the library upload picker. That works — but a design system and the page that uses it are now two independent manual uploads. If a user saves a page that has a design system attached and forgets to also upload the design system, the page arrives in the destination library with a dangling reference and none of its styling.

This is a follow-up exploration, not a locked spec — the approach below is a proposal.

Current behavior

• A page links to its design system through the _fl_ds_ref post meta, which stores the design system's UUID (DesignSystemPostType::META_UUID / _fl_ds_uuid), or the none opt-out sentinel. Resolution lives in DesignSystemPostType::resolve_for_post() → get_by_uuid() in bb-ai-design-system.
• LibraryItemPostController::save_to_library() uploads a single post: get_save_data() collects the post row, get_post_meta(), terms, and media, then calls CloudClient->libraries->create_item().
• _fl_ds_ref rides along inside that meta blob, but the fl-design-system post it points at is never uploaded — and even if it were, the raw UUID won't line up with a freshly-imported DS post on another site.

Desired behavior

When a page that has a resolvable design system attached (_fl_ds_ref set to a real UUID, not none) is saved to a library, the attached design system is automatically created as a library item in the same library, so the page's styling travels with it. Uploading a design system on its own (via the picker from #517) still works as-is.

Proposed approach (exploratory)

Keep Assistant generic — don't hard-code the _fl_ds_ref meta key into LibraryItemPostController. Instead mirror the #517 pattern: add a filter in the save path that lets a plugin declare companion items to create alongside the primary post.

• Assistant side: in save_to_library(), after the primary create_item() succeeds, apply something like apply_filters( 'fl_assistant_library_companion_items', [], $post, $library_id ). Each returned item is created in the same library (dedup so a DS shared by several pages in one upload session isn't created twice).
• BB AI side: hook that filter, read _fl_ds_ref on the page, resolve the fl-design-system post by UUID, and return it as a companion item using the same save-data shape.

This keeps the dependency knowledge in the plugin that owns the concept, consistent with how fl_assistant_post_types_known was solved. A narrower DS-specific integration is the alternative — see open questions.

Files

• backend/src/Controllers/Cloud/Libraries/LibraryItemPostController.php — save_to_library(), get_save_data() (this repo)
• Companion hook lives in bb-ai-design-system: packages/design-system-runtime/backend/Page/PageOverrideProvider.php (_fl_ds_ref linkage) and .../DesignSystem/DesignSystemPostType.php (already hooks fl_assistant_post_types_known; would add the companion-items hook alongside)

Open questions

1. sync_to_library too? Should re-syncing a page also re-sync its attached DS, or is auto-include save-only?
2. Import remapping. Auto-upload is only half the loop. On import, the DS must be recreated and the page's _fl_ds_ref remapped to the new local UUID, or the reference still won't resolve on the destination. This may warrant its own issue.
3. Dedup scope. One page → one DS is simple; a multi-select upload of several pages sharing one DS needs dedup within the batch.
4. Generic filter vs. DS-specific. Is a general "companion items" hook worth it, or a narrower DS-only integration in Assistant?