face-up 0.0.0 → 0.0.1

package/types/.kiro/steering/emc-json-serializability.md

@@ -0,0 +1,306 @@
+# EMC Configuration JSON Serializability
+
+## Core Principle
+
+**All content in `emc.mjs` files MUST be JSON-serializable without loss of information.**
+
+The `render()` function at the bottom of every `emc.mjs` file exports the configuration as JSON via `JSON.stringify()`. This JSON is what gets loaded at runtime by enhancement classes and the be-hive system.
+
+## Why This Matters
+
+1. **Runtime Loading**: Enhancement classes import `emc.json` (not `emc.mjs`) using JSON import assertions
+2. **Declarative Configuration**: The JSON file is the source of truth for how enhancements are configured
+3. **Portability**: JSON files can be loaded by any JavaScript environment without executing code
+4. **Security**: JSON is safer than executing arbitrary JavaScript
+5. **Tooling**: JSON can be validated, transformed, and analyzed by standard tools
+
+## What IS JSON-Serializable
+
+✅ **Allowed in emc.mjs:**
+- Strings: `"hello"`
+- Numbers: `42`, `3.14`
+- Booleans: `true`, `false`
+- null: `null`
+- Arrays: `[1, 2, 3]`
+- Plain objects: `{ key: "value" }`
+- Nested structures: `{ items: [{ id: 1 }, { id: 2 }] }`
+
+## What is NOT JSON-Serializable
+
+❌ **NOT allowed in emc.mjs:**
+- **Functions**: `parser: (v) => v.split(',')` ❌
+- **Class constructors**: `spawn: MyClass` ❌
+- **Symbols**: `Symbol('key')` ❌
+- **undefined**: `value: undefined` ❌ (becomes `null` or omitted)
+- **Regular expressions**: `/pattern/` ❌ (becomes `{}`)
+- **Dates**: `new Date()` ❌ (becomes string)
+- **WeakMap/WeakSet**: Not serializable
+- **Circular references**: Will throw error
+
+## How to Handle Non-Serializable Values
+
+### Functions (Parsers, Handlers)
+
+**❌ WRONG:**
+```javascript
+// emc.mjs
+function myParser(value) {
+    return value.split(',');
+}
+
+export const emc = {
+    enhConfig: {
+        withAttrs: {
+            _base: {
+                parser: myParser  // ❌ Function reference - not JSON serializable
+            }
+        }
+    }
+};
+```
+
+**✅ CORRECT:**
+```javascript
+// emc.mjs
+export const emc = {
+    enhConfig: {
+        withAttrs: {
+            _base: {
+                parser: 'myParser'  // ✅ String reference - JSON serializable
+            }
+        }
+    }
+};
+
+// Separate parser file: parser.js
+export default function myParser(value) {
+    return value.split(',');
+}
+
+// HTML: Load parser separately
+<script type="emc-parser" src="./parser.js" parser-name="myParser"></script>
+```
+
+### Class Constructors (spawn)
+
+**❌ WRONG:**
+```javascript
+// emc.mjs
+import { MyEnhancement } from './my-enhancement.js';
+
+export const emc = {
+    enhConfig: {
+        spawn: MyEnhancement  // ❌ Class reference - not JSON serializable
+    }
+};
+```
+
+**✅ CORRECT:**
+```javascript
+// emc.mjs
+export const emc = {
+    enhConfig: {
+        spawn: 'my-enhancement/my-enhancement.js'  // ✅ Module path string
+    }
+};
+```
+
+### Regular Expressions
+
+**❌ WRONG:**
+```javascript
+export const emc = {
+    enhConfig: {
+        withAttrs: {
+            pattern: /^test-/  // ❌ RegExp - becomes {}
+        }
+    }
+};
+```
+
+**✅ CORRECT:**
+```javascript
+export const emc = {
+    enhConfig: {
+        withAttrs: {
+            pattern: '^test-'  // ✅ String - can be converted to RegExp at runtime
+        }
+    }
+};
+```
+
+## Validation
+
+Every `emc.mjs` file should end with:
+
+```javascript
+export function render() {
+    return JSON.stringify(emc, null, 4);
+}
+
+console.log(render());
+```
+
+**Test your configuration:**
+```bash
+node emc.mjs
+```
+
+If this command:
+- ✅ Outputs valid JSON → Configuration is serializable
+- ❌ Throws an error → You have non-serializable values
+- ❌ Outputs `{}` or `null` for a property → You have a non-serializable value that was silently dropped
+
+## Common Mistakes
+
+### Mistake 1: Inline Parser Functions
+
+```javascript
+// ❌ WRONG
+export const emc = {
+    enhConfig: {
+        withAttrs: {
+            _base: {
+                parser: (v) => v.split(',')  // Lost in JSON.stringify()
+            }
+        }
+    }
+};
+```
+
+**Result:** The `parser` property becomes `{}` in the JSON output.
+
+### Mistake 2: Importing Classes
+
+```javascript
+// ❌ WRONG
+import { MyClass } from './my-class.js';
+
+export const emc = {
+    customData: {
+        helperClass: MyClass  // Lost in JSON.stringify()
+    }
+};
+```
+
+**Result:** The `helperClass` property becomes `{}` in the JSON output.
+
+### Mistake 3: Using undefined
+
+```javascript
+// ❌ WRONG
+export const emc = {
+    customData: {
+        optionalValue: undefined  // Omitted in JSON.stringify()
+    }
+};
+```
+
+**Result:** The `optionalValue` property is completely omitted from the JSON output.
+
+## Best Practices
+
+1. **Always test serialization**: Run `node emc.mjs` to verify output
+2. **Use string references**: For parsers, use string names that resolve at runtime
+3. **Use module paths**: For `spawn`, use string paths to modules
+4. **Document external dependencies**: If your config references parsers by name, document which parser files are required
+5. **Avoid undefined**: Use `null` instead if you need to represent "no value"
+6. **Keep it simple**: The simpler your config, the easier it is to serialize
+
+## Example: Complete Valid emc.mjs
+
+```javascript
+// @ts-check
+
+/** @import {EMC} from './types/mount-observer/types' */;
+/** @import {AllProps, Actions} from './types/my-enhancement/types' */
+/** @import {RAConfig} from './types/roundabout/types' */
+
+/**
+ * @type {EMC<any, AllProps, Element, RAConfig<AllProps, Actions> >}
+ */
+export const emc = {
+    enhConfig: {
+        enhKey: 'MyEnhancement',
+        spawn: 'my-enhancement/my-enhancement.js',  // ✅ String path
+        withAttrs: {
+            base: 'my-enhancement',
+            value: '${base}-value',
+            _value: {
+                parser: 'myParser'  // ✅ String reference
+            }
+        }
+    },
+    customData: {
+        weakRef: {
+            properties: ['enhancedElement']
+        },
+        actions: {
+            hydrate: {
+                ifAllOf: ['value', 'enhancedElement']
+            }
+        },
+        defaultPropVals: {
+            enabled: true,
+            count: 0
+        }
+    }
+};
+
+export function render() {
+    return JSON.stringify(emc, null, 4);
+}
+
+console.log(render());
+```
+
+## Enforcement
+
+This principle should be enforced by:
+
+1. **Code review**: Check that all `emc.mjs` files only contain JSON-serializable values
+2. **Testing**: Run `node emc.mjs` as part of the build process
+3. **Documentation**: Reference this principle in conversion guides
+4. **Linting**: Consider adding a custom lint rule to detect non-serializable values
+
+## Dependency Version Management
+
+**Always use specific point versions** in `package.json`, not version ranges:
+
+✅ **CORRECT:**
+```json
+{
+  "dependencies": {
+    "be-hive": "0.1.9",
+    "mount-observer": "0.0.16",
+    "roundabout-lib": "0.0.2"
+  }
+}
+```
+
+❌ **WRONG:**
+```json
+{
+  "dependencies": {
+    "be-hive": "^0.1.9",      // ❌ Caret allows minor/patch updates
+    "mount-observer": "~0.0.16", // ❌ Tilde allows patch updates
+    "roundabout-lib": "*"     // ❌ Wildcard allows any version
+  }
+}
+```
+
+**Why specific versions?**
+- **Reproducible builds**: Same versions across all environments
+- **No surprises**: Prevents automatic breaking changes
+- **Explicit control**: You decide when to update
+- **Easier debugging**: Know exactly which version caused an issue
+- **Consistent testing**: CI/CD uses same versions as development
+
+**When to update:**
+Use `npm run update` (which runs `ncu -u && npm install`) to explicitly update all dependencies to their latest versions. Review the changes and test thoroughly before committing.
+
+## Related Documentation
+
+- [Scoped Parser Registry](https://github.com/bahrus/mount-observer#scoped-parser-registry-for-emc-scripts)
+- [EMC Scripts](https://github.com/bahrus/mount-observer#element-mount-configuration-emc-scripts)
+- [Conversion Instructions](../ConversionInstructions.md)