@portel/photon-core 2.5.2 → 2.5.4

package/dist/compiler.d.ts

@@ -7,14 +7,6 @@
  * NOTE: No esbuild dependency in package.json — the consumer must provide it.
  * Uses `await import('esbuild')` for dynamic resolution.
  */
-/**
- * Compile a .photon.ts file to JavaScript and cache the result
- *
- * @param tsFilePath - Absolute path to the TypeScript source file
- * @param options.cacheDir - Directory to store compiled output
- * @param options.content - Optional pre-read file content (avoids extra read)
- * @returns Absolute path to the compiled .mjs file
- */
 export declare function compilePhotonTS(tsFilePath: string, options: {
     cacheDir: string;
     content?: string;

package/dist/compiler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../src/compiler.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9C,OAAO,CAAC,MAAM,CAAC,CA+BjB"}
+{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../src/compiler.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA2GH,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9C,OAAO,CAAC,MAAM,CAAC,CAmCjB"}

package/dist/compiler.js

@@ -18,8 +18,81 @@ import * as crypto from 'crypto';
  * @param options.content - Optional pre-read file content (avoids extra read)
  * @returns Absolute path to the compiled .mjs file
  */
+/**
+ * Transform arrays to reactive collections for PhotonMCP classes
+ *
+ * ZERO-EFFORT REACTIVITY: If a class extends PhotonMCP and has array properties,
+ * this transform automatically:
+ * 1. Injects `import { Array as ReactiveArray } from '@portel/photon-core'`
+ * 2. Transforms `= []` to `= new ReactiveArray()` for class properties
+ *
+ * Result: Developers write normal code, arrays are automatically reactive.
+ *
+ * ```typescript
+ * // Developer writes this (normal TypeScript):
+ * export default class TodoList extends PhotonMCP {
+ *   items: Task[] = [];
+ *   async add(text: string) { this.items.push({...}); }
+ * }
+ *
+ * // Compiler transforms to:
+ * import { Array as ReactiveArray } from '@portel/photon-core';
+ * export default class TodoList extends PhotonMCP {
+ *   items = new ReactiveArray();
+ *   async add(text: string) { this.items.push({...}); }  // Auto-emits!
+ * }
+ * ```
+ */
+function transformReactiveCollections(source) {
+    // Check if this is a PhotonMCP class (extends PhotonMCP)
+    const isPhotonMCP = /class\s+\w+\s+extends\s+PhotonMCP\b/.test(source);
+    if (!isPhotonMCP)
+        return source;
+    // Check if there are array properties with = [] that need transformation
+    // Look for patterns like: `items: Type[] = []` or `items = []` (class properties)
+    const hasArrayLiterals = /\w+\s*:\s*[^=\n]+\[\]\s*=\s*\[\s*\]/.test(source) || // typed: Type[] = []
+        /^\s+\w+\s*=\s*\[\s*\](?=\s*[;\n])/m.test(source); // simple: prop = []
+    if (!hasArrayLiterals)
+        return source;
+    let transformed = source;
+    // Check if Array is already imported from photon-core
+    const hasArrayImport = /import\s*\{[^}]*\bArray\b[^}]*\}\s*from\s*['"]@portel\/photon-core['"]/.test(source);
+    if (!hasArrayImport) {
+        // Inject ReactiveArray import (using alias to avoid shadowing issues)
+        // Find the photon-core import and add ReactiveArray to it, or add new import
+        const photonCoreImport = source.match(/import\s*\{([^}]+)\}\s*from\s*['"]@portel\/photon-core['"]/);
+        if (photonCoreImport) {
+            // Add to existing import
+            const existingImports = photonCoreImport[1];
+            transformed = transformed.replace(photonCoreImport[0], `import { ${existingImports}, Array as ReactiveArray } from '@portel/photon-core'`);
+        }
+        else {
+            // Add new import at the top (after any existing imports)
+            const lastImportMatch = source.match(/^import\s+.+$/gm);
+            if (lastImportMatch) {
+                const lastImport = lastImportMatch[lastImportMatch.length - 1];
+                transformed = transformed.replace(lastImport, `${lastImport}\nimport { Array as ReactiveArray } from '@portel/photon-core';`);
+            }
+            else {
+                // No imports, add at top
+                transformed = `import { Array as ReactiveArray } from '@portel/photon-core';\n${transformed}`;
+            }
+        }
+    }
+    // Determine the Array constructor name to use
+    const arrayConstructor = hasArrayImport ? 'Array' : 'ReactiveArray';
+    // Transform class property declarations with type annotation = []
+    // Handles: items: Task[] = []; | items: Array<T> = [];
+    transformed = transformed.replace(/(\w+)\s*:\s*(?:Array<[^>]+>|[^=\n]+\[\])\s*=\s*\[\s*\]/g, `$1 = new ${arrayConstructor}()`);
+    // Transform class property without type annotation (indented, at start of line)
+    // Skip local variables (const/let/var)
+    transformed = transformed.replace(/^(\s+)(\w+)\s*=\s*\[\s*\](?=\s*[;\n])/gm, `$1$2 = new ${arrayConstructor}()`);
+    return transformed;
+}
 export async function compilePhotonTS(tsFilePath, options) {
-    const source = options.content ?? (await fs.readFile(tsFilePath, 'utf-8'));
+    let source = options.content ?? (await fs.readFile(tsFilePath, 'utf-8'));
+    // Transform reactive collection literals before compilation
+    source = transformReactiveCollections(source);
     const hash = crypto.createHash('sha256').update(source).digest('hex').slice(0, 16);
     const fileName = path.basename(tsFilePath, '.ts');
     const cachedJsPath = path.join(options.cacheDir, `${fileName}.${hash}.mjs`);

package/dist/compiler.js.map

@@ -1 +1 @@
-{"version":3,"file":"compiler.js","sourceRoot":"","sources":["../src/compiler.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,aAAa,CAAC;AAClC,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAEjC;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,UAAkB,EAClB,OAA+C;IAE/C,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;IAC3E,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAEnF,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IAClD,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,QAAQ,IAAI,IAAI,MAAM,CAAC,CAAC;IAE5E,iCAAiC;IACjC,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;QAC9B,OAAO,YAAY,CAAC;IACtB,CAAC;IAAC,MAAM,CAAC;QACP,uBAAuB;IACzB,CAAC;IAED,wDAAwD;IACxD,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,SAAS,CAAC,MAAM,EAAE;QAC7C,MAAM,EAAE,IAAI;QACZ,MAAM,EAAE,KAAK;QACb,MAAM,EAAE,QAAQ;QAChB,SAAS,EAAE,QAAQ;KACpB,CAAC,CAAC;IAEH,gCAAgC;IAChC,MAAM,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEtD,4BAA4B;IAC5B,MAAM,EAAE,CAAC,SAAS,CAAC,YAAY,EAAE,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAEvD,OAAO,YAAY,CAAC;AACtB,CAAC"}
+{"version":3,"file":"compiler.js","sourceRoot":"","sources":["../src/compiler.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,aAAa,CAAC;AAClC,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAEjC;;;;;;;GAOG;AACH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,SAAS,4BAA4B,CAAC,MAAc;IAClD,yDAAyD;IACzD,MAAM,WAAW,GAAG,qCAAqC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACvE,IAAI,CAAC,WAAW;QAAE,OAAO,MAAM,CAAC;IAEhC,yEAAyE;IACzE,kFAAkF;IAClF,MAAM,gBAAgB,GACpB,qCAAqC,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,qBAAqB;QAC3E,oCAAoC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAK,oBAAoB;IAE7E,IAAI,CAAC,gBAAgB;QAAE,OAAO,MAAM,CAAC;IAErC,IAAI,WAAW,GAAG,MAAM,CAAC;IAEzB,sDAAsD;IACtD,MAAM,cAAc,GAAG,wEAAwE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAE7G,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,sEAAsE;QACtE,6EAA6E;QAC7E,MAAM,gBAAgB,GAAG,MAAM,CAAC,KAAK,CACnC,4DAA4D,CAC7D,CAAC;QAEF,IAAI,gBAAgB,EAAE,CAAC;YACrB,yBAAyB;YACzB,MAAM,eAAe,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC;YAC5C,WAAW,GAAG,WAAW,CAAC,OAAO,CAC/B,gBAAgB,CAAC,CAAC,CAAC,EACnB,YAAY,eAAe,uDAAuD,CACnF,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,yDAAyD;YACzD,MAAM,eAAe,GAAG,MAAM,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;YACxD,IAAI,eAAe,EAAE,CAAC;gBACpB,MAAM,UAAU,GAAG,eAAe,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;gBAC/D,WAAW,GAAG,WAAW,CAAC,OAAO,CAC/B,UAAU,EACV,GAAG,UAAU,iEAAiE,CAC/E,CAAC;YACJ,CAAC;iBAAM,CAAC;gBACN,yBAAyB;gBACzB,WAAW,GAAG,kEAAkE,WAAW,EAAE,CAAC;YAChG,CAAC;QACH,CAAC;IACH,CAAC;IAED,8CAA8C;IAC9C,MAAM,gBAAgB,GAAG,cAAc,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC;IAEpE,kEAAkE;IAClE,uDAAuD;IACvD,WAAW,GAAG,WAAW,CAAC,OAAO,CAC/B,yDAAyD,EACzD,YAAY,gBAAgB,IAAI,CACjC,CAAC;IAEF,gFAAgF;IAChF,uCAAuC;IACvC,WAAW,GAAG,WAAW,CAAC,OAAO,CAC/B,yCAAyC,EACzC,cAAc,gBAAgB,IAAI,CACnC,CAAC;IAEF,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,UAAkB,EAClB,OAA+C;IAE/C,IAAI,MAAM,GAAG,OAAO,CAAC,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;IAEzE,4DAA4D;IAC5D,MAAM,GAAG,4BAA4B,CAAC,MAAM,CAAC,CAAC;IAE9C,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAEnF,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IAClD,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,QAAQ,IAAI,IAAI,MAAM,CAAC,CAAC;IAE5E,iCAAiC;IACjC,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;QAC9B,OAAO,YAAY,CAAC;IACtB,CAAC;IAAC,MAAM,CAAC;QACP,uBAAuB;IACzB,CAAC;IAED,wDAAwD;IACxD,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,SAAS,CAAC,MAAM,EAAE;QAC7C,MAAM,EAAE,IAAI;QACZ,MAAM,EAAE,KAAK;QACb,MAAM,EAAE,QAAQ;QAChB,SAAS,EAAE,QAAQ;KACpB,CAAC,CAAC;IAEH,gCAAgC;IAChC,MAAM,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEtD,4BAA4B;IAC5B,MAAM,EAAE,CAAC,SAAS,CAAC,YAAY,EAAE,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAEvD,OAAO,YAAY,CAAC;AACtB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@portel/photon-core",
-  "version": "2.5.2",
+  "version": "2.5.4",
   "description": "Core library for parsing, loading, and managing .photon.ts files - runtime-agnostic foundation for building custom Photon runtimes",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/compiler.ts

@@ -20,11 +20,108 @@ import * as crypto from 'crypto';
  * @param options.content - Optional pre-read file content (avoids extra read)
  * @returns Absolute path to the compiled .mjs file
  */
+/**
+ * Transform arrays to reactive collections for PhotonMCP classes
+ *
+ * ZERO-EFFORT REACTIVITY: If a class extends PhotonMCP and has array properties,
+ * this transform automatically:
+ * 1. Injects `import { Array as ReactiveArray } from '@portel/photon-core'`
+ * 2. Transforms `= []` to `= new ReactiveArray()` for class properties
+ *
+ * Result: Developers write normal code, arrays are automatically reactive.
+ *
+ * ```typescript
+ * // Developer writes this (normal TypeScript):
+ * export default class TodoList extends PhotonMCP {
+ *   items: Task[] = [];
+ *   async add(text: string) { this.items.push({...}); }
+ * }
+ *
+ * // Compiler transforms to:
+ * import { Array as ReactiveArray } from '@portel/photon-core';
+ * export default class TodoList extends PhotonMCP {
+ *   items = new ReactiveArray();
+ *   async add(text: string) { this.items.push({...}); }  // Auto-emits!
+ * }
+ * ```
+ */
+function transformReactiveCollections(source: string): string {
+  // Check if this is a PhotonMCP class (extends PhotonMCP)
+  const isPhotonMCP = /class\s+\w+\s+extends\s+PhotonMCP\b/.test(source);
+  if (!isPhotonMCP) return source;
+
+  // Check if there are array properties with = [] that need transformation
+  // Look for patterns like: `items: Type[] = []` or `items = []` (class properties)
+  const hasArrayLiterals =
+    /\w+\s*:\s*[^=\n]+\[\]\s*=\s*\[\s*\]/.test(source) || // typed: Type[] = []
+    /^\s+\w+\s*=\s*\[\s*\](?=\s*[;\n])/m.test(source);     // simple: prop = []
+
+  if (!hasArrayLiterals) return source;
+
+  let transformed = source;
+
+  // Check if Array is already imported from photon-core
+  const hasArrayImport = /import\s*\{[^}]*\bArray\b[^}]*\}\s*from\s*['"]@portel\/photon-core['"]/.test(source);
+
+  if (!hasArrayImport) {
+    // Inject ReactiveArray import (using alias to avoid shadowing issues)
+    // Find the photon-core import and add ReactiveArray to it, or add new import
+    const photonCoreImport = source.match(
+      /import\s*\{([^}]+)\}\s*from\s*['"]@portel\/photon-core['"]/
+    );
+
+    if (photonCoreImport) {
+      // Add to existing import
+      const existingImports = photonCoreImport[1];
+      transformed = transformed.replace(
+        photonCoreImport[0],
+        `import { ${existingImports}, Array as ReactiveArray } from '@portel/photon-core'`
+      );
+    } else {
+      // Add new import at the top (after any existing imports)
+      const lastImportMatch = source.match(/^import\s+.+$/gm);
+      if (lastImportMatch) {
+        const lastImport = lastImportMatch[lastImportMatch.length - 1];
+        transformed = transformed.replace(
+          lastImport,
+          `${lastImport}\nimport { Array as ReactiveArray } from '@portel/photon-core';`
+        );
+      } else {
+        // No imports, add at top
+        transformed = `import { Array as ReactiveArray } from '@portel/photon-core';\n${transformed}`;
+      }
+    }
+  }
+
+  // Determine the Array constructor name to use
+  const arrayConstructor = hasArrayImport ? 'Array' : 'ReactiveArray';
+
+  // Transform class property declarations with type annotation = []
+  // Handles: items: Task[] = []; | items: Array<T> = [];
+  transformed = transformed.replace(
+    /(\w+)\s*:\s*(?:Array<[^>]+>|[^=\n]+\[\])\s*=\s*\[\s*\]/g,
+    `$1 = new ${arrayConstructor}()`
+  );
+
+  // Transform class property without type annotation (indented, at start of line)
+  // Skip local variables (const/let/var)
+  transformed = transformed.replace(
+    /^(\s+)(\w+)\s*=\s*\[\s*\](?=\s*[;\n])/gm,
+    `$1$2 = new ${arrayConstructor}()`
+  );
+
+  return transformed;
+}
+
 export async function compilePhotonTS(
   tsFilePath: string,
   options: { cacheDir: string; content?: string },
 ): Promise<string> {
-  const source = options.content ?? (await fs.readFile(tsFilePath, 'utf-8'));
+  let source = options.content ?? (await fs.readFile(tsFilePath, 'utf-8'));
+
+  // Transform reactive collection literals before compilation
+  source = transformReactiveCollections(source);
+
   const hash = crypto.createHash('sha256').update(source).digest('hex').slice(0, 16);
 
   const fileName = path.basename(tsFilePath, '.ts');