face-up 0.0.0 → 0.0.1

package/types/.kiro/specs/conversion-template/README.md

@@ -0,0 +1,128 @@
+# Conversion Template
+
+This spec template provides a structured approach to converting legacy be-* enhancement projects to the modern architecture.
+
+## When to Use This Template
+
+Use this template when:
+- You want to track conversion progress step-by-step
+- You're converting a be-* project for the first time
+- You want to review each step before proceeding
+- Multiple people are involved in the conversion
+- You want a record of the conversion process
+
+## How to Use This Template
+
+### Option 1: Copy to Project (Recommended)
+
+1. Copy this entire folder to your project's `.kiro/specs/` directory:
+   ```bash
+   cp -r types/.kiro/specs/conversion-template .kiro/specs/conversion-[project-name]
+   ```
+
+2. Update placeholders in all files:
+   - Replace `[PROJECT_NAME]` with your project name (e.g., "be-clonable")
+   - Replace `[project-name]` with kebab-case name (e.g., "be-clonable")
+   - Replace `[ClassName]` with PascalCase name (e.g., "BeClonable")
+   - Replace `[emoji]` with actual emoji if applicable (e.g., "⿻")
+
+3. Work through the tasks in `tasks.md` sequentially
+
+4. Use Kiro to execute tasks: "execute task 1", "execute task 2", etc.
+
+### Option 2: Use as Reference
+
+Simply reference this template while doing a manual conversion:
+- Follow the requirements in `requirements.md`
+- Understand the architecture from `design.md`
+- Use `tasks.md` as a checklist
+
+## Template Structure
+
+### requirements.md
+- User stories for each conversion step
+- Correctness properties to verify
+- Success criteria
+- Non-functional requirements
+
+### design.md
+- Architecture overview with diagrams
+- Component design for each file type
+- Data flow explanations
+- Design decisions and rationale
+- Alternatives considered
+
+### tasks.md
+- Detailed task breakdown (11 major tasks, 60+ subtasks)
+- Task dependencies
+- Execution notes for each step
+- Reference to ConversionInstructions.md
+
+## Key Features
+
+### Comprehensive Coverage
+All 10 conversion steps from ConversionInstructions.md are covered with detailed subtasks
+
+### Verification Built-in
+Task 11 provides comprehensive verification steps to ensure conversion success
+
+### Reference Integration
+All files reference ConversionInstructions.md for detailed step-by-step instructions
+
+### Kiro-Optimized
+- Uses file references: `#[[file:../../ConversionInstructions.md]]`
+- Task format compatible with Kiro's task execution
+- Structured for spec-driven development workflow
+
+## Example Usage with Kiro
+
+```
+User: "I want to convert be-clonable to the modern architecture"
+
+Kiro: "I can help you with that. Would you like to:
+1. Create a tracked conversion spec (recommended for first-time conversions)
+2. Do a direct conversion (faster, for experienced users)
+
+User: "Create a spec"
+
+Kiro: [Creates spec from template, updates placeholders]
+      "I've created a conversion spec at .kiro/specs/conversion-be-clonable/
+       Let's start with Task 1: Migrate Type Definitions. Ready to begin?"
+
+User: "Yes"
+
+Kiro: [Executes Task 1, marks subtasks complete]
+      "Task 1 complete. Type definitions migrated to types/be-clonable/.
+       Ready for Task 2: Archive Legacy Implementation?"
+```
+
+## Success Criteria
+
+A successful conversion using this template should result in:
+- ✅ All tasks marked complete
+- ✅ `npm run build` succeeds
+- ✅ `npm test` passes
+- ✅ No TypeScript errors
+- ✅ Legacy code preserved in legacy/ folder
+- ✅ Modern architecture verified
+
+## Related Files
+
+- `../../ConversionInstructions.md` - Detailed step-by-step instructions
+- `../../.kiro/steering/conversion-guide.md` - Kiro steering guidance
+- Reference implementations:
+  - [be-a-beacon](https://github.com/bahrus/be-a-beacon)
+  - [be-committed](https://github.com/bahrus/be-committed)
+  - [be-decked-with](https://github.com/bahrus/be-decked-with)
+
+## Customization
+
+Feel free to customize this template for your specific needs:
+- Add project-specific tasks
+- Modify verification steps
+- Add additional correctness properties
+- Extend design documentation
+
+## Feedback
+
+If you find issues with this template or have suggestions for improvement, please update the template in the types repository so all projects benefit.

package/types/.kiro/specs/conversion-template/design.md

@@ -0,0 +1,360 @@
+# Design: Convert [PROJECT_NAME] to Modern Architecture
+
+## Architecture Overview
+
+This conversion transforms a legacy be-enhanced project to the modern be-hive + roundabout architecture. The design follows a systematic 10-step process that preserves the original implementation while building the new architecture.
+
+## System Context
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Legacy Architecture                      │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
+│  │   emc.js     │  │ be-*.js      │  │  ts-refs/    │     │
+│  │ (runtime)    │  │ extends BE   │  │  (types)     │     │
+│  └──────────────┘  └──────────────┘  └──────────────┘     │
+│         │                  │                  │             │
+│         └──────────────────┴──────────────────┘             │
+│                           │                                 │
+│                    be-enhanced                              │
+│                    trans-render                             │
+└─────────────────────────────────────────────────────────────┘
+                           │
+                    [CONVERSION]
+                           │
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│                     Modern Architecture                      │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
+│  │  emc.mjs     │  │ be-*.js      │  │   types/     │     │
+│  │ (build)      │  │ standalone   │  │  (types)     │     │
+│  └──────────────┘  └──────────────┘  └──────────────┘     │
+│         │                  │                  │             │
+│         ▼                  │                  │             │
+│    emc.json                └──────────────────┘             │
+│         │                           │                       │
+│         └───────────────────────────┘                       │
+│                           │                                 │
+│                      be-hive                                │
+│                   roundabout-lib                            │
+│                  assign-gingerly                            │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Component Design
+
+### 1. Type Definitions (types/[project-name]/types.d.ts)
+
+**Purpose:** Standalone type definitions without external dependencies
+
+**Structure:**
+```typescript
+// EndUserProps: Properties exposed to HTML attributes
+export interface EndUserProps {
+    // User-facing properties
+}
+
+// AllProps: Internal properties + EndUserProps
+export interface AllProps extends EndUserProps {
+    enhancedElement: Element;  // Required
+    // Internal properties
+}
+
+// Type aliases for convenience
+export type AP = AllProps;
+export type PAP = Partial<AP>;
+export type ProPAP = Promise<PAP>;
+
+// Actions: Methods that implement behavior
+export interface Actions {
+    methodName(self: AP): ProPAP | void;
+}
+```
+
+**Key Design Decisions:**
+- No external imports (standalone)
+- `enhancedElement` is explicit in AllProps
+- BAP removed (was AP & BEAllProps)
+- All action methods use AP instead of BAP
+
+### 2. Build Configuration (emc.mjs)
+
+**Purpose:** Generate static JSON configuration at build time
+
+**Structure:**
+```javascript
+//@ts-check
+import {emc} from './emc.mjs';
+
+/** @import {EMC} from './types/mount-observer/types' */;
+/** @import {AllProps, Actions} from './types/[project-name]/types' */
+/** @import {RAConfig} from './types/roundabout/types' */
+
+export const emc = {
+    enhConfig: {
+        enhKey: 'EnhancementKey',
+        spawn: '[project-name]/[project-name].js',
+        withAttrs: {
+            base: '[project-name]',
+            // Attribute mappings using ${base} template
+        }
+    },
+    customData: {
+        weakRef: {
+            properties: ['enhancedElement']
+        },
+        actions: { /* reactive action triggers */ },
+        handlers: { /* event handlers */ },
+        compacts: { /* compact syntax mappings */ }
+    }
+}
+
+export function render(){
+    return JSON.stringify(emc, null, 4);
+}
+
+console.log(render());
+```
+
+**Key Design Decisions:**
+- withAttrs replaces base/branches/map (cleaner syntax)
+- customData contains reactive configuration
+- weakRef configuration tells roundabout which properties to store as weak references
+- No propDefaults/propInfo (inferred by roundabout)
+- Build-time only (not loaded in browser)
+
+### 3. Enhancement Class (be-[project-name].js)
+
+**Purpose:** Implement enhancement behavior using modern patterns
+
+**Structure:**
+```javascript
+// @ts-check
+/**
+ * @type {EMC<any, AllProps, Element, RAConfig<AllProps, Actions>>}
+ */
+import emc from './emc.json' with {type: 'json'};
+
+class Be[ClassName] {
+    
+    // Constructor: Initialize and setup
+    constructor(enhancedElement, ctx, initVals) {
+        // Call init with enhancedElement
+    }
+    
+    // Init: Setup roundabout and defaults
+    async init(self, enhancedElement, initVals) {
+        // Configure roundabout with weakRef support
+        // Set defaults via assignGingerly (including enhancedElement)
+    }
+    
+    // Action methods (copied from legacy)
+    async actionMethod(self) { /* ... */ }
+}
+
+export { Be[ClassName] }
+```
+
+**Key Design Decisions:**
+- No base class (standalone)
+- No WeakRef boilerplate - roundabout handles it via customData.weakRef
+- Constructor pattern (enhancedElement, ctx, initVals)
+- Init receives enhancedElement as parameter
+- Roundabout integration in init
+- assignGingerly for property assignment (including enhancedElement)
+- No static config (moved to emc.mjs)
+
+### 4. Emoji Shorthand ([emoji].mjs)
+
+**Purpose:** Generate variant configuration for emoji syntax
+
+**Structure:**
+```javascript
+import myJSON from './emc.json' with {type: 'json'};
+
+const emc = {
+    enhConfig: {
+        ...myJSON.enhConfig,
+        enhKey: '[emoji]',
+        withAttrs: {
+            ...myJSON.enhConfig.withAttrs,
+            base: '[emoji]'
+        }
+    }
+}
+
+export function render(){
+    return JSON.stringify(emc, null, 4);
+}
+
+console.log(render());
+```
+
+**Key Design Decisions:**
+- Extends base configuration
+- Only overrides enhKey and base
+- Minimal duplication
+
+## Data Flow
+
+### Build Time
+```
+emc.mjs ──[node]──> emc.json
+   │
+   └──> [emoji].mjs ──[node]──> [emoji].json
+```
+
+### Runtime
+```
+HTML Attribute
+    │
+    ▼
+be-hive (mount observer)
+    │
+    ▼
+emc.json (configuration)
+    │
+    ▼
+Enhancement Class Constructor
+    │
+    ▼
+init() method
+    │
+    ├──> roundabout (reactive properties)
+    │
+    └──> assignGingerly (property assignment)
+         │
+         ▼
+    Action Methods
+```
+
+## Conversion Process Design
+
+### Phase 1: Preparation (Steps 1-2)
+- Migrate types to new submodule
+- Archive legacy implementation
+- **Rationale:** Preserve original, establish clean slate
+
+### Phase 2: Configuration (Steps 3-5)
+- Update package.json
+- Configure imports.html
+- Establish coding standards
+- **Rationale:** Set up infrastructure before code changes
+
+### Phase 3: Types (Step 6)
+- Modernize type definitions
+- **Rationale:** Types inform implementation
+
+### Phase 4: Build System (Steps 7-8)
+- Create emc.mjs
+- Configure VS Code
+- **Rationale:** Build system generates runtime config
+
+### Phase 5: Implementation (Steps 9-10)
+- Create modern enhancement class
+- Create emoji shorthand (optional)
+- **Rationale:** Implement using new architecture
+
+## Error Handling
+
+### Build Errors
+- Validate JSON output from .mjs files
+- Check for missing required fields
+- Verify TypeScript types
+
+### Runtime Errors
+- Missing properties → roundabout handles reactivity
+- WeakRef.deref() returns undefined → roundabout throws appropriate error
+- Action method errors → propagate naturally
+
+## Testing Strategy
+
+### Unit Tests
+- Test action methods in isolation
+- Verify property reactivity
+- Check event handlers
+
+### Integration Tests
+- Test full enhancement lifecycle
+- Verify attribute parsing
+- Check emoji shorthand equivalence
+
+### Build Tests
+- Verify JSON generation
+- Check TypeScript compilation
+- Validate configuration structure
+
+## Performance Considerations
+
+### Build Time
+- JSON generation is fast (< 1s per file)
+- No complex transformations
+
+### Runtime
+- WeakRef allows garbage collection
+- Roundabout provides efficient reactivity
+- No unnecessary object creation
+
+### Memory
+- WeakRef handled automatically by roundabout for configured properties
+- No circular references
+- Clean teardown
+
+## Security Considerations
+
+- No eval or dynamic code execution
+- Trusted types support (TODO in some methods)
+- Attribute values sanitized by browser
+
+## Compatibility
+
+### Browser Support
+- Modern ES modules required
+- Import maps required
+- WeakRef required (modern browsers) - handled by roundabout
+
+### Backward Compatibility
+- HTML usage unchanged
+- Same attribute names
+- Same behavior
+
+## Migration Path
+
+### For Users
+- No changes required to HTML
+- Can use either full name or emoji
+- Behavior identical to legacy
+
+### For Developers
+- Follow 10-step process
+- Reference ConversionInstructions.md
+- Use this spec for tracking
+
+## Alternatives Considered
+
+### Alternative 1: Keep be-enhanced
+**Rejected:** Legacy architecture has limitations, not actively maintained
+
+### Alternative 2: Complete Rewrite
+**Rejected:** Too risky, loses proven behavior
+
+### Alternative 3: Gradual Migration
+**Rejected:** Creates hybrid state, more complex
+
+### Selected: Systematic Conversion
+**Rationale:** Preserves legacy, clear process, proven pattern
+
+## Open Questions
+
+- Should we automate any steps?
+- Should we create a CLI tool for conversion?
+- How do we handle edge cases in static config?
+
+## References
+
+- ConversionInstructions.md (detailed steps)
+- be-a-beacon (reference implementation)
+- be-committed (reference implementation)
+- be-decked-with (reference implementation)
+- assign-gingerly README (withAttrs documentation)
+- roundabout-lib (reactive properties)

package/types/.kiro/specs/conversion-template/requirements.md

@@ -0,0 +1,191 @@
+# Requirements: Convert [PROJECT_NAME] to Modern Architecture
+
+## Overview
+
+Convert the legacy [PROJECT_NAME] enhancement project from the be-enhanced architecture to the modern be-hive + roundabout architecture.
+
+## Reference Documentation
+
+Complete conversion instructions: `#[[file:../../ConversionInstructions.md]]`
+
+## User Stories
+
+### US-1: Migrate Type Definitions
+**As a** developer  
+**I want** type definitions in the modern `types` submodule  
+**So that** the project uses the clearer naming convention
+
+**Acceptance Criteria:**
+- Type definitions exist at `types/[project-name]/types.d.ts`
+- `ts-refs` submodule is removed
+- Types are accessible from the new location
+
+### US-2: Preserve Legacy Implementation
+**As a** developer  
+**I want** the original implementation preserved in a `legacy` folder  
+**So that** I can reference it during and after conversion
+
+**Acceptance Criteria:**
+- All `.js`, `.mjs`, and `.json` files (except package*.json) are moved to `legacy/`
+- Legacy folder contains complete working implementation
+- Root directory is ready for new implementation
+
+### US-3: Update Dependencies
+**As a** developer  
+**I want** modern dependencies (be-hive, roundabout-lib)  
+**So that** the project uses the new architecture
+
+**Acceptance Criteria:**
+- package.json has be-hive, mount-observer, and roundabout-lib dependencies
+- Legacy dependencies (be-enhanced, trans-render) are removed
+- Build scripts use the new pattern (node emc.mjs > emc.json)
+- `npm run update` successfully updates to latest versions
+
+### US-4: Configure Import Maps
+**As a** developer  
+**I want** a proper imports.html file  
+**So that** browser-based ES modules work correctly
+
+**Acceptance Criteria:**
+- imports.html exists with correct import map structure
+- Project maps to "/" root
+- Dependencies map to /node_modules/[package]/
+
+### US-5: Establish Coding Standards
+**As a** developer  
+**I want** documented coding standards  
+**So that** the codebase follows consistent conventions
+
+**Acceptance Criteria:**
+- `.kiro/steering/coding-standards.md` exists
+- Standards cover import maps, file extensions, and TypeScript support
+- Standards are automatically included in Kiro context
+
+### US-6: Modernize Type Definitions
+**As a** developer  
+**I want** standalone type definitions without external dependencies  
+**So that** types are portable and self-contained
+
+**Acceptance Criteria:**
+- No imports from trans-render or be-enhanced in types
+- `EndUserProps` doesn't extend IEnhancement
+- `AllProps` includes `enhancedElement: Element`
+- `BAP` type is removed, replaced with `AP`
+
+### US-7: Create Build Configuration
+**As a** developer  
+**I want** an emc.mjs build script  
+**So that** configuration is generated at build time
+
+**Acceptance Criteria:**
+- emc.mjs exists with proper structure
+- Uses withAttrs pattern for attribute mapping
+- customData contains actions, handlers, compacts from legacy config
+- No propDefaults or propInfo (inferred by roundabout)
+- `npm run build` generates valid emc.json
+
+### US-8: Configure VS Code
+**As a** developer  
+**I want** VS Code file nesting configured  
+**So that** generated JSON files are organized under their source .mjs files
+
+**Acceptance Criteria:**
+- `.vscode/settings.json` exists
+- File nesting patterns configured for *.mjs -> *.json
+- File nesting is enabled
+
+### US-8a: Configure Auto-Build Hook (Optional)
+**As a** developer  
+**I want** automatic rebuilding when .mjs files are saved  
+**So that** JSON files stay in sync without manual build commands
+
+**Acceptance Criteria:**
+- Kiro hook exists for fileEdited event
+- Hook watches emc.mjs and emoji .mjs files
+- Hook runs npm run build on save
+- JSON files regenerate automatically
+
+### US-9: Create Modern Enhancement Class
+**As a** developer  
+**I want** a modern enhancement class using roundabout  
+**So that** the implementation uses the new architecture
+
+**Acceptance Criteria:**
+- be-[project-name].js exists
+- Class doesn't extend anything
+- Uses constructor with enhancedElement, ctx, initVals
+- Uses WeakRef for element storage
+- init method integrates roundabout
+- Default values set via assignGingerly in init
+- All action methods copied with BAP replaced by AP
+- No bootUp or legacy imports
+
+### US-10: Create Emoji Shorthand (Optional)
+**As a** developer  
+**I want** an emoji shorthand configuration  
+**So that** users can use the shorter emoji syntax
+
+**Acceptance Criteria:**
+- [emoji].mjs exists (if emoji in README title)
+- Imports and extends emc.json
+- Overrides enhKey and base to use emoji
+- `npm run build` generates [emoji].json
+
+## Correctness Properties
+
+### CP-1: Build Success
+**Property:** The project builds without errors  
+**Test:** Run `npm run build` and verify exit code 0
+
+### CP-2: Test Compatibility
+**Property:** All existing tests pass with the new implementation  
+**Test:** Run `npm test` and verify all tests pass
+
+### CP-3: Configuration Validity
+**Property:** Generated JSON configuration is valid and complete  
+**Test:** Parse emc.json and verify all required fields exist
+
+### CP-4: Type Safety
+**Property:** TypeScript checking passes with @ts-check  
+**Test:** No TypeScript errors in be-[project-name].js
+
+### CP-5: Legacy Preservation
+**Property:** Legacy implementation is complete and unchanged  
+**Test:** Verify all original files exist in legacy/ folder
+
+## Non-Functional Requirements
+
+### Performance
+- Build time should be under 5 seconds
+- No runtime performance degradation vs legacy
+
+### Maintainability
+- Code follows documented standards
+- Clear separation between configuration and implementation
+- Consistent with other converted projects
+
+### Documentation
+- ConversionInstructions.md is the source of truth
+- Each step is clearly documented
+- Examples provided for complex transformations
+
+## Dependencies
+
+- Node.js and npm installed
+- Access to types submodule
+- Original project in working state
+
+## Constraints
+
+- Must maintain backward compatibility with existing HTML usage
+- Must preserve all existing functionality
+- Must follow the 10-step conversion process in order
+
+## Success Metrics
+
+- ✅ All 10 conversion steps completed
+- ✅ `npm run build` succeeds
+- ✅ `npm test` passes
+- ✅ No TypeScript errors
+- ✅ Legacy code preserved
+- ✅ Modern architecture verified