# be-* Enhancement Conversion Guide

## Purpose

This steering file provides guidance for converting legacy "be-*" enhancement projects to the modern architecture. When a user requests help with converting a be-* project, use this guide to structure the conversion process.

**Important:** This guide is specifically for **enhancements** (declarative behaviors added to existing HTML elements via attributes). It does NOT apply to custom elements.

## Reference Documentation

- **Converting legacy enhancements:** `EnhancementConversionInstructions.md` in the types repository root
- **Creating new enhancements from scratch:** `NewEnhancementInstructions.md` in the types repository root

Always reference the appropriate document based on whether the project is a legacy conversion or a brand new enhancement.

## Conversion Approach

### When to Use Spec-Based Conversion

For systematic, trackable conversions, create a spec using the conversion template:
- User wants to track progress through the conversion
- User wants to review each step before proceeding
- User is learning the conversion process
- Multiple people are involved in the conversion

### When to Use Direct Conversion

For quick, automated conversions:
- User is familiar with the conversion process
- User wants rapid execution without step-by-step review
- The project is straightforward with no special cases

## Key Principles

1. **Preserve Legacy Code**: Always move existing implementation to the `legacy` folder before making changes
2. **Follow the Order**: The conversion steps have dependencies - follow them in sequence
3. **Verify Each Step**: After each major step, verify the changes work as expected
4. **Reference Examples**: Point to **be-clonable** (most up-to-date), be-committed, and be-decked-with as reference implementations. Prefer be-clonable as it has the latest architectural improvements. Note: be-a-beacon is too simple to serve as a good example - it doesn't use roundabout due to its minimal requirements.

## Common Patterns

### Project Structure Recognition

Identify legacy projects by these characteristics:
- Has `be-enhanced` or `trans-render` dependencies
- Class extends `BE` from be-enhanced
- Has static `config` object in the enhancement class
- Uses `emc.js` with `base`, `branches`, `map` pattern
- Has `ts-refs` submodule for types

### Modern Architecture Indicators

Recognize already-converted projects by:
- Has `be-hive` and `roundabout-lib` dependencies
- Has `emc.mjs` build script
- Has `types` submodule (not `ts-refs`)
- Class doesn't extend anything
- Uses constructor with `enhancedElement`, `ctx`, `initVals` parameters

## Conversion Workflow

When a user asks to convert a be-* project:

1. **Assess the project**: Determine if it's legacy or already converted
2. **Offer spec creation**: Ask if they want a tracked conversion (spec) or direct conversion
3. **Execute systematically**: Follow the 10 steps in ConversionInstructions.md
4. **Run npm run update**: After Step 3 (updating package.json), ALWAYS run `npm run update` to install dependencies before proceeding
5. **Verify at milestones**: After steps 3, 7, and 10, suggest running `npm run build` and `npm test`
6. **Reference the guide**: Point users to specific sections of ConversionInstructions.md as needed
7. **Use be-clonable as reference**: When implementation details are unclear, refer to [be-clonable](https://github.com/bahrus/be-clonable) as it has the most refined patterns

## Special Cases

### No Emoji Shorthand
If the README doesn't have an emoji in the title:
- Skip Step 10 (emoji .mjs creation)
- Update package.json build script to only generate emc.json

### Complex Static Config
If the legacy static config has unusual patterns:
- Carefully map `propDefaults` to the init method
- Preserve any custom logic in action methods
- Document any patterns that don't fit the standard conversion

### Custom Dependencies
If the project uses trans-render utilities:
- Keep those imports in the action methods
- Don't remove them unless they're only used in static config

### mount-observer/refid/hostish.js Replacement
References to `mount-observer/refid/hostish.js` have been replaced by `inferencer/upSearch.js`. This requires adding the `inferencer` package as a dependency. When converting a project that imports from `mount-observer/refid/hostish.js`:
- Replace the import path with `inferencer/upSearch.js`
- Add `inferencer` to the project's dependencies in `package.json`

## Success Criteria

A successful conversion should:
- ✅ Build without errors (`npm run build`)
- ✅ Pass existing tests (`npm test`)
- ✅ Have all legacy files in the `legacy` folder
- ✅ Have modern architecture files (emc.mjs, be-*.js, types)
- ✅ Have updated dependencies (be-hive, roundabout-lib)
- ✅ Generate valid JSON configuration files

## File Reference

Always reference `#[[file:EnhancementConversionInstructions.md]]` for the complete step-by-step conversion instructions.
For new enhancements, reference `#[[file:NewEnhancementInstructions.md]]`.