feat: overhaul preset definitions

[Julusian]

bitfocus/companion#3931

The aim here is to formalise a slightly more hierarchical structure for presets.

Instead of a flat structure with a 'category' name set on each preset, this has changed to a lightly nested structure.

Instead of arbitrary 'text' presets, there is now a concept of groups instead. Each 'section' (previously category) can now contain either an array of groups or presets.

Local variables are supported! Currently limited to just 'user value' type.

There is a new concept of a 'matrix' group. Inspired a little by the github actions matrix syntax.
Instead of having to define the same preset multiple times with just changing an option to an action/feedback, some value substitution can be done. This is done via local-variables, with the matrix overriding the default value of those local variables

Types have been tweaked a little too, to tidy up a few patches of messiness that have crept in.

Summary by CodeRabbit

• New Features
  • Organize presets into structured sections and groups with support for preset referencing and categorization.
  • Template-based preset generation with configurable template variables and common variable overrides.
  • Local variables support in presets with configurable startup values.
  • Enhanced action configuration with richer grouping and long-press action options.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

🗂️ Base branches to auto review (1)

• develop

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The PR introduces a new preset structuring system by adding CompanionPresetSection types to organize presets into grouped sections. The setPresetDefinitions method signature is updated across the codebase to accept structure definitions alongside presets. Preset types are reorganized into a dedicated module hierarchy with expanded typing support.

Changes

Cohort / File(s)	Summary
Method Signature Updates packages/companion-module-base/src/host-api/context.ts, packages/companion-module-base/src/module-api/base.ts, packages/companion-module-host/src/context.ts, packages/companion-module-host/src/instance.ts	Updated setPresetDefinitions method signature to accept two parameters: structure: CompanionPresetSection<TManifest>[] and presets: CompanionPresetDefinitions<TManifest>, replacing the previous single presets parameter.
Module Restructuring packages/companion-module-base/src/module-api/index.ts, packages/companion-module-base/src/module-api/preset/main.ts	Reorganized preset exports to use new module path structure (./preset/main.js), consolidating preset-related types into a dedicated module hierarchy.
Type System Expansion packages/companion-module-base/src/module-api/preset/definition.ts	Significantly expanded preset definition system with new types: CompanionPresetDefinition, CompanionSimplePresetDefinition, CompanionPresetAction, CompanionButtonStepActions, CompanionSimplePresetLocalVariable, and supporting option/value utility types. Replaced legacy composite preset types.
Preset Structure Framework packages/companion-module-base/src/module-api/preset/structure.ts	Introduced new module providing typed preset organization model with CompanionPresetSection, CompanionPresetGroup (discriminated union with Simple and Template variants), and CompanionPresetGroupBase.
Validation Layer Update packages/companion-module-host/src/internal/presets.ts	Updated validatePresetDefinitions to accept new structure parameter and refined preset type filtering from 'button' to 'simple' preset type.

Poem

🎨 Presets now organize with grace,
Sections grouping each preset's place,
Structure flows with actions strong,
Types refined, the code's now long,
Changes flourish, all looks right! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Merge Conflict Detection	⚠️ Warning	❌ Merge conflicts detected (11 files): ⚔️ packages/companion-module-base/assets/manifest.schema.json (content) ⚔️ packages/companion-module-base/src/host-api/context.ts (content) ⚔️ packages/companion-module-base/src/module-api/action.ts (content) ⚔️ packages/companion-module-base/src/module-api/base.ts (content) ⚔️ packages/companion-module-base/src/module-api/feedback.ts (content) ⚔️ packages/companion-module-base/src/module-api/index.ts (content) ⚔️ packages/companion-module-host/src/context.ts (content) ⚔️ packages/companion-module-host/src/instance.ts (content) ⚔️ packages/companion-module-host/src/internal/actions.ts (content) ⚔️ packages/companion-module-host/src/internal/feedback.ts (content) ⚔️ packages/companion-module-host/src/internal/presets.ts (content) These conflicts must be resolved before merging into feat/2.0.	Resolve conflicts locally and push changes to this branch.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: overhaul preset definitions' accurately summarizes the main change—a comprehensive restructuring of the preset system with new hierarchical structures, group types, and local variable support.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Julusian]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 6

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

packages/companion-module-host/src/instance.ts (1)

287-295: ⚠️ Potential issue | 🔴 Critical

Pre-existing: this.destroy() looks like it recurses infinitely

Hey, this isn't from your changes, but I noticed await this.destroy() on line 291 calls the InstanceWrapper.destroy() method itself — likely should be await this.#instance.destroy(). This would cause a stack overflow when called. Might be worth fixing while you're in the neighborhood! 😊

🐛 Suggested fix

 async destroy(): Promise<void> {
   await this.#lifecycleQueue.add(async () => {
     if (!this.#initialized) throw new Error('Not initialized')
-    await this.destroy()
+    await this.#instance.destroy()
     this.#initialized = false
   })
 }

🧹 Nitpick comments (2)

packages/companion-module-base/src/module-api/preset/definition.ts (1)

7-7: Consider using import type for CompanionActionSchema

CompanionActionSchema appears to only be used in type positions (generic constraints). Using import type would make that intent clearer and ensure it's erased at compile time. No big deal though!

-import { CompanionActionSchema } from '../action.js'
+import type { CompanionActionSchema } from '../action.js'

packages/companion-module-host/src/internal/presets.ts (1)

11-16: structure parameter currently unused, but validation idea is worth considering

Thanks for the contribution! I noticed the structure parameter was added to the function signature but isn't actually used in the validation logic right now. Since CompanionPresetSection.definitions can contain CompanionPresetReference[] (which are preset ID strings), it could be handy down the road to validate that those references actually point to existing keys in the presets map.

That said, totally understand if that's being saved for a later iteration—just wanted to flag it in case it's helpful! The current validation logic for action and feedback IDs is looking solid. 🎉