Module content_pack 

Local content packs (#155): a versioned, user-controlled bundle of break ideas (hint pools) and guided routines that the user imports/exports as a plain JSON file. No cloud, no remote registry — everything is a local file the user explicitly picks.

Import is additive and non-clobbering: pack hints are appended to the existing pools (exact duplicates skipped) and pack routines are added to custom_routines (ids colliding with a bundled starter or an existing custom routine are skipped). Export captures the current pools + custom_routines, so export→import round-trips losslessly.

The schema is versioned and intentionally extensible: sound and theme/overlay bundling are deferred to a future version bump rather than crammed in here.

parse_pack / validate_pack / merge_pack / export_pack are pure and fully unit-tested; the file I/O and IPC wrapping live in commands::content_pack.

Structs

AddedContent

The concrete content a merge added, so an uninstall can remove exactly those entries (the merge-and-track model). Mirrors PackHints plus the ids of routines that were appended to custom_routines.

ContentPack

A content pack: versioned, named, with optional hints and routines.

MergeSummary

What an import added, surfaced to the UI so the user sees the effect.

PackHints

Hint pools a pack can carry. Each maps to the matching Settings pool; all optional so a pack can ship only what it wants.

Constants

CONTENT_PACK_VERSION

Schema version this build reads and writes. Bumped only on a breaking-change to the bundle shape.

MAX_HINTS_PER_POOL 🔒

MAX_ROUTINES 🔒

Defensive caps so a malformed or hostile bundle can’t bloat settings or stall the UI. Generous relative to any hand-curated pack.

MAX_STEPS_PER_ROUTINE 🔒

MAX_STEP_SECONDS 🔒

MAX_STRING_LEN 🔒

Functions

check_string 🔒

export_pack

Build a content pack capturing the user’s current pools + custom routines, so it can be written to a file and imported elsewhere.

merge_pack

Merge a validated pack into settings, returning only the summary counts. Thin wrapper over merge_pack_tracked for the content-pack import path, which has no uninstall and so doesn’t need the AddedContent record.

merge_pack_tracked

Merge a validated pack into settings, recording exactly what was added. Append hints to each pool and routines to custom_routines, skipping ids that collide with a bundled starter or an already-present custom routine. Non-destructive — nothing is removed or overwritten. Returns the summary counts plus the concrete AddedContent for a later remove_content.

merge_pool 🔒

Append additions to pool, skipping blanks and exact duplicates (against both the existing pool and earlier additions). Returns the strings actually added (so an uninstall can remove exactly those). Order-preserving and non-clobbering.

parse_pack

Parse a content pack from JSON, mapping serde errors to a user-facing string. Does not validate beyond shape — call validate_pack next.

remove_content

Remove exactly the content recorded in added from settings (the uninstall half of merge-and-track): drop the recorded hint strings from each pool and the recorded routine ids from custom_routines. Tolerant of intervening user edits — anything already gone is simply skipped. Returns (hints_removed, routines_removed).

sanitize_imported_step 🔒

Clear any field of a step arriving from an UNSIGNED imported pack that only the signed-plugin installer is allowed to populate.

serialize_pack

Serialise a pack to pretty JSON.

validate_pack

Validate a parsed pack: supported version, non-empty name, size caps, and well-formed routines (non-empty id/label, 1..=N steps with non-empty text and a sane duration, no duplicate ids within the pack). Returns a clear, user-facing error on the first problem.