@portel/photon-core 2.8.4 → 2.9.0

package/dist/utils/duration.js

@@ -0,0 +1,64 @@
+/**
+ * Duration and rate parsing utilities for functional tags
+ *
+ * Supports duration strings: 30s, 5m, 1h, 1d, 500ms
+ * Supports rate expressions: 10/min, 100/h, 5/s
+ */
+const DURATION_MULTIPLIERS = {
+    ms: 1,
+    s: 1_000,
+    sec: 1_000,
+    m: 60_000,
+    min: 60_000,
+    h: 3_600_000,
+    hr: 3_600_000,
+    d: 86_400_000,
+    day: 86_400_000,
+};
+/**
+ * Parse a duration string into milliseconds
+ * @example parseDuration('30s') → 30000
+ * @example parseDuration('5m') → 300000
+ * @example parseDuration('500ms') → 500
+ * @example parseDuration('1234') → 1234 (raw ms fallback)
+ */
+export function parseDuration(input) {
+    const trimmed = input.trim();
+    const match = trimmed.match(/^(\d+(?:\.\d+)?)(ms|s|sec|m|min|h|hr|d|day)$/i);
+    if (match) {
+        const value = parseFloat(match[1]);
+        const unit = match[2].toLowerCase();
+        return Math.round(value * DURATION_MULTIPLIERS[unit]);
+    }
+    // Fallback: raw milliseconds
+    const raw = parseInt(trimmed, 10);
+    return isNaN(raw) ? 0 : raw;
+}
+const RATE_WINDOW_MULTIPLIERS = {
+    s: 1_000,
+    sec: 1_000,
+    m: 60_000,
+    min: 60_000,
+    h: 3_600_000,
+    hr: 3_600_000,
+    d: 86_400_000,
+    day: 86_400_000,
+};
+/**
+ * Parse a rate expression into count and window
+ * @example parseRate('10/min') → { count: 10, windowMs: 60000 }
+ * @example parseRate('100/h') → { count: 100, windowMs: 3600000 }
+ */
+export function parseRate(input) {
+    const trimmed = input.trim();
+    const match = trimmed.match(/^(\d+)\/(s|sec|m|min|h|hr|d|day)$/i);
+    if (match) {
+        const count = parseInt(match[1], 10);
+        const unit = match[2].toLowerCase();
+        return { count, windowMs: RATE_WINDOW_MULTIPLIERS[unit] };
+    }
+    // Fallback: treat as count per minute
+    const count = parseInt(trimmed, 10);
+    return { count: isNaN(count) ? 10 : count, windowMs: 60_000 };
+}
+//# sourceMappingURL=duration.js.map

package/dist/utils/duration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration.js","sourceRoot":"","sources":["../../src/utils/duration.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,oBAAoB,GAA2B;IACnD,EAAE,EAAE,CAAC;IACL,CAAC,EAAE,KAAK;IACR,GAAG,EAAE,KAAK;IACV,CAAC,EAAE,MAAM;IACT,GAAG,EAAE,MAAM;IACX,CAAC,EAAE,SAAS;IACZ,EAAE,EAAE,SAAS;IACb,CAAC,EAAE,UAAU;IACb,GAAG,EAAE,UAAU;CAChB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,+CAA+C,CAAC,CAAC;IAC7E,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACnC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;QACpC,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAC;IACxD,CAAC;IACD,6BAA6B;IAC7B,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAClC,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;AAC9B,CAAC;AAED,MAAM,uBAAuB,GAA2B;IACtD,CAAC,EAAE,KAAK;IACR,GAAG,EAAE,KAAK;IACV,CAAC,EAAE,MAAM;IACT,GAAG,EAAE,MAAM;IACX,CAAC,EAAE,SAAS;IACZ,EAAE,EAAE,SAAS;IACb,CAAC,EAAE,UAAU;IACb,GAAG,EAAE,UAAU;CAChB,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAC;IAClE,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACrC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;QACpC,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,uBAAuB,CAAC,IAAI,CAAC,EAAE,CAAC;IAC5D,CAAC;IACD,sCAAsC;IACtC,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IACpC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;AAChE,CAAC"}

package/dist/watcher.d.ts

@@ -0,0 +1,62 @@
+/**
+ * PhotonWatcher
+ *
+ * Reusable file watcher for .photon.ts/.photon.js files.
+ * Extracted from the daemon's battle-tested implementation with:
+ * - Symlink resolution (macOS fs.watch fix)
+ * - Debouncing (configurable, default 100ms)
+ * - Temp file filtering (.swp, .bak, ~, .DS_Store, vim 4913)
+ * - Rename handling (macOS sed -i new inode → re-establish watcher)
+ * - Directory watching for added/removed photons
+ *
+ * Zero new dependencies — uses Node.js fs.watch().
+ */
+import { EventEmitter } from 'events';
+export interface PhotonWatcherOptions {
+    /** Directories to scan for photon files */
+    directories: string[];
+    /** File extensions to watch (default: ['.photon.ts', '.photon.js']) */
+    extensions?: string[];
+    /** Debounce interval in ms (default: 100) */
+    debounceMs?: number;
+    /** Watch directories for new/removed files (default: true) */
+    watchDirectories?: boolean;
+}
+export declare class PhotonWatcher extends EventEmitter {
+    private options;
+    private fileWatchers;
+    private dirWatchers;
+    private debounceTimers;
+    /** Maps watchPath (real) → { photonName, originalPath } */
+    private watchedFiles;
+    /** Tracks known photon files per directory for diff-based add/remove detection */
+    private knownFiles;
+    private running;
+    constructor(options: PhotonWatcherOptions);
+    /**
+     * Start watching. Scans directories for existing photon files and sets up watchers.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop all watchers and clean up.
+     */
+    stop(): Promise<void>;
+    /**
+     * Watch a specific photon file. Called automatically during scan,
+     * but can also be called manually for dynamically discovered files.
+     */
+    watchFile(photonName: string, filePath: string): void;
+    /**
+     * Stop watching a specific file by its original path.
+     */
+    unwatchFile(filePath: string): void;
+    /**
+     * Get a map of currently watched files: photonName → originalPath
+     */
+    getWatchedFiles(): Map<string, string>;
+    private handleFileEvent;
+    private unwatchByRealPath;
+    private scanDirectory;
+    private watchDirectory;
+}
+//# sourceMappingURL=watcher.d.ts.map

package/dist/watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watcher.d.ts","sourceRoot":"","sources":["../src/watcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAKtC,MAAM,WAAW,oBAAoB;IACnC,2CAA2C;IAC3C,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AA8BD,qBAAa,aAAc,SAAQ,YAAY;IAC7C,OAAO,CAAC,OAAO,CAAiC;IAChD,OAAO,CAAC,YAAY,CAAmC;IACvD,OAAO,CAAC,WAAW,CAAmC;IACtD,OAAO,CAAC,cAAc,CAAoD;IAC1E,2DAA2D;IAC3D,OAAO,CAAC,YAAY,CAAmE;IACvF,kFAAkF;IAClF,OAAO,CAAC,UAAU,CAAkC;IACpD,OAAO,CAAC,OAAO,CAAS;gBAEZ,OAAO,EAAE,oBAAoB;IAUzC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAY5B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAsB3B;;;OAGG;IACH,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IA6BrD;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAUnC;;OAEG;IACH,eAAe,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IAYtC,OAAO,CAAC,eAAe;IAqCvB,OAAO,CAAC,iBAAiB;YAeX,aAAa;IAkD3B,OAAO,CAAC,cAAc;CAkCvB"}

package/dist/watcher.js

@@ -0,0 +1,270 @@
+/**
+ * PhotonWatcher
+ *
+ * Reusable file watcher for .photon.ts/.photon.js files.
+ * Extracted from the daemon's battle-tested implementation with:
+ * - Symlink resolution (macOS fs.watch fix)
+ * - Debouncing (configurable, default 100ms)
+ * - Temp file filtering (.swp, .bak, ~, .DS_Store, vim 4913)
+ * - Rename handling (macOS sed -i new inode → re-establish watcher)
+ * - Directory watching for added/removed photons
+ *
+ * Zero new dependencies — uses Node.js fs.watch().
+ */
+import { EventEmitter } from 'events';
+import * as fs from 'fs';
+import * as fsPromises from 'fs/promises';
+import * as path from 'path';
+/** Temp/junk files to ignore */
+const IGNORED_PATTERNS = [
+    /\.swp$/,
+    /\.bak$/,
+    /~$/,
+    /\.DS_Store$/,
+    /^4913$/, // vim temp file check
+    /\.tmp$/,
+    /^\.#/, // emacs lock files
+];
+function isIgnored(filename) {
+    return IGNORED_PATTERNS.some((p) => p.test(filename));
+}
+function isPhotonFile(filename, extensions) {
+    return extensions.some((ext) => filename.endsWith(ext));
+}
+function photonNameFromFile(filename, extensions) {
+    for (const ext of extensions) {
+        if (filename.endsWith(ext)) {
+            return filename.slice(0, -ext.length);
+        }
+    }
+    return null;
+}
+export class PhotonWatcher extends EventEmitter {
+    options;
+    fileWatchers = new Map();
+    dirWatchers = new Map();
+    debounceTimers = new Map();
+    /** Maps watchPath (real) → { photonName, originalPath } */
+    watchedFiles = new Map();
+    /** Tracks known photon files per directory for diff-based add/remove detection */
+    knownFiles = new Map();
+    running = false;
+    constructor(options) {
+        super();
+        this.options = {
+            directories: options.directories,
+            extensions: options.extensions ?? ['.photon.ts', '.photon.js'],
+            debounceMs: options.debounceMs ?? 100,
+            watchDirectories: options.watchDirectories ?? true,
+        };
+    }
+    /**
+     * Start watching. Scans directories for existing photon files and sets up watchers.
+     */
+    async start() {
+        if (this.running)
+            return;
+        this.running = true;
+        for (const dir of this.options.directories) {
+            await this.scanDirectory(dir);
+            if (this.options.watchDirectories) {
+                this.watchDirectory(dir);
+            }
+        }
+    }
+    /**
+     * Stop all watchers and clean up.
+     */
+    async stop() {
+        this.running = false;
+        for (const [, watcher] of this.fileWatchers) {
+            watcher.close();
+        }
+        this.fileWatchers.clear();
+        for (const [, watcher] of this.dirWatchers) {
+            watcher.close();
+        }
+        this.dirWatchers.clear();
+        for (const [, timer] of this.debounceTimers) {
+            clearTimeout(timer);
+        }
+        this.debounceTimers.clear();
+        this.watchedFiles.clear();
+        this.knownFiles.clear();
+    }
+    /**
+     * Watch a specific photon file. Called automatically during scan,
+     * but can also be called manually for dynamically discovered files.
+     */
+    watchFile(photonName, filePath) {
+        // Resolve symlink so fs.watch() fires when the real file changes.
+        // On macOS, fs.watch on a symlink only detects changes to the symlink inode itself.
+        let watchPath = filePath;
+        try {
+            watchPath = fs.realpathSync(filePath);
+        }
+        catch {
+            // Symlink target doesn't exist yet — fall back to original path
+        }
+        if (this.fileWatchers.has(watchPath))
+            return;
+        try {
+            const watcher = fs.watch(watchPath, (eventType) => {
+                this.handleFileEvent(eventType, watchPath, photonName, filePath);
+            });
+            watcher.on('error', (err) => {
+                this.emit('error', err, { photonName, path: filePath });
+                this.unwatchByRealPath(watchPath);
+            });
+            this.fileWatchers.set(watchPath, watcher);
+            this.watchedFiles.set(watchPath, { photonName, originalPath: filePath });
+        }
+        catch (err) {
+            this.emit('error', err, { photonName, path: filePath });
+        }
+    }
+    /**
+     * Stop watching a specific file by its original path.
+     */
+    unwatchFile(filePath) {
+        // Find the real path entry
+        for (const [watchPath, info] of this.watchedFiles) {
+            if (info.originalPath === filePath) {
+                this.unwatchByRealPath(watchPath);
+                return;
+            }
+        }
+    }
+    /**
+     * Get a map of currently watched files: photonName → originalPath
+     */
+    getWatchedFiles() {
+        const result = new Map();
+        for (const [, info] of this.watchedFiles) {
+            result.set(info.photonName, info.originalPath);
+        }
+        return result;
+    }
+    // ──────────────────────────────────────────────────────────────────────────────
+    // Internal
+    // ──────────────────────────────────────────────────────────────────────────────
+    handleFileEvent(eventType, watchPath, photonName, originalPath) {
+        // Debounce
+        const existing = this.debounceTimers.get(watchPath);
+        if (existing)
+            clearTimeout(existing);
+        this.debounceTimers.set(watchPath, setTimeout(() => {
+            this.debounceTimers.delete(watchPath);
+            // On macOS, editors like sed -i replace the file (new inode),
+            // killing the watcher. Re-watch via original path to re-resolve symlinks.
+            if (eventType === 'rename') {
+                this.unwatchByRealPath(watchPath);
+                if (fs.existsSync(originalPath)) {
+                    this.watchFile(photonName, originalPath);
+                }
+                else {
+                    this.emit('removed', photonName);
+                    return;
+                }
+            }
+            if (!fs.existsSync(originalPath)) {
+                this.emit('removed', photonName);
+                return;
+            }
+            this.emit('changed', photonName, originalPath);
+        }, this.options.debounceMs));
+    }
+    unwatchByRealPath(watchPath) {
+        const watcher = this.fileWatchers.get(watchPath);
+        if (watcher) {
+            watcher.close();
+            this.fileWatchers.delete(watchPath);
+        }
+        this.watchedFiles.delete(watchPath);
+        const timer = this.debounceTimers.get(watchPath);
+        if (timer) {
+            clearTimeout(timer);
+            this.debounceTimers.delete(watchPath);
+        }
+    }
+    async scanDirectory(dir) {
+        let entries;
+        try {
+            entries = await fsPromises.readdir(dir, { withFileTypes: true });
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                this.emit('error', error, { directory: dir });
+            }
+            return;
+        }
+        const currentFiles = new Set();
+        for (const entry of entries) {
+            if (!entry.isFile() && !entry.isSymbolicLink())
+                continue;
+            if (isIgnored(entry.name))
+                continue;
+            if (!isPhotonFile(entry.name, this.options.extensions))
+                continue;
+            const photonName = photonNameFromFile(entry.name, this.options.extensions);
+            if (!photonName)
+                continue;
+            const filePath = path.join(dir, entry.name);
+            currentFiles.add(entry.name);
+            // Only emit 'added' and watch if this is a new file
+            const known = this.knownFiles.get(dir);
+            if (!known || !known.has(entry.name)) {
+                this.emit('added', photonName, filePath);
+                this.watchFile(photonName, filePath);
+            }
+        }
+        // Detect removals (files that were known but no longer present)
+        const previousFiles = this.knownFiles.get(dir);
+        if (previousFiles) {
+            for (const filename of previousFiles) {
+                if (!currentFiles.has(filename)) {
+                    const photonName = photonNameFromFile(filename, this.options.extensions);
+                    if (photonName) {
+                        const filePath = path.join(dir, filename);
+                        this.unwatchFile(filePath);
+                        this.emit('removed', photonName);
+                    }
+                }
+            }
+        }
+        this.knownFiles.set(dir, currentFiles);
+    }
+    watchDirectory(dir) {
+        if (this.dirWatchers.has(dir))
+            return;
+        try {
+            const watcher = fs.watch(dir, (eventType, filename) => {
+                if (!filename)
+                    return;
+                if (isIgnored(filename))
+                    return;
+                if (!isPhotonFile(filename, this.options.extensions))
+                    return;
+                // Debounce directory events
+                const key = `dir:${dir}`;
+                const existing = this.debounceTimers.get(key);
+                if (existing)
+                    clearTimeout(existing);
+                this.debounceTimers.set(key, setTimeout(() => {
+                    this.debounceTimers.delete(key);
+                    if (this.running) {
+                        this.scanDirectory(dir);
+                    }
+                }, this.options.debounceMs));
+            });
+            watcher.on('error', (err) => {
+                this.emit('error', err, { directory: dir });
+            });
+            this.dirWatchers.set(dir, watcher);
+        }
+        catch (err) {
+            this.emit('error', err, { directory: dir });
+        }
+    }
+}
+//# sourceMappingURL=watcher.js.map

package/dist/watcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watcher.js","sourceRoot":"","sources":["../src/watcher.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@portel/photon-core",
-  "version": "2.8.4",
+  "version": "2.9.0",
   "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",
@@ -33,7 +33,7 @@
     "build": "tsc",
     "clean": "rm -rf dist",
     "prepublishOnly": "npm run clean && npm run build",
-    "test": "npm run build && npx tsx tests/channels.test.ts && npx tsx tests/shared-utils.test.ts && npx tsx tests/collections.test.ts && npx tsx tests/audit.test.ts && npx tsx tests/memory.test.ts",
+    "test": "npm run build && npx tsx tests/channels.test.ts && npx tsx tests/shared-utils.test.ts && npx tsx tests/collections.test.ts && npx tsx tests/audit.test.ts && npx tsx tests/memory.test.ts && npx tsx tests/instance-store.test.ts && npx tsx tests/watcher.test.ts",
     "test:channels": "npx tsx tests/channels.test.ts"
   },
   "keywords": [

package/src/base.ts

@@ -1,12 +1,12 @@
 /**
- * PhotonMCP Base Class
+ * Photon Base Class
  *
- * Optional base class for creating Photon MCPs.
+ * Optional base class for creating Photons.
  * You don't need to extend this - any class with async methods works!
  *
  * Usage:
  * ```typescript
- * export default class Calculator extends PhotonMCP {
+ * export default class Calculator extends Photon {
  *   /**
  *    * Add two numbers together
  *    * @param a First number
@@ -29,7 +29,7 @@
  *
  * With MCP access (requires runtime support):
  * ```typescript
- * export default class SlackReporter extends PhotonMCP {
+ * export default class SlackReporter extends Photon {
  *   async report() {
  *     const github = this.mcp('github');
  *     const issues = await github.call('list_issues', { repo: 'foo/bar' });
@@ -46,13 +46,13 @@ import { withLock as withLockHelper } from './decorators.js';
 import { MemoryProvider } from './memory.js';
 
 /**
- * Simple base class for creating Photon MCPs
+ * Simple base class for creating Photons
  *
- * - Class name = MCP name
+ * - Class name = Photon name
  * - Public async methods = Tools
  * - Return value = Tool result
  */
-export class PhotonMCP {
+export class Photon {
   /**
    * Photon name (MCP name) - set by runtime loader
    * Used to identify the source of emitted events for injected photon routing
@@ -247,7 +247,7 @@ export class PhotonMCP {
 
     // Get all property names from prototype chain
     let current = prototype;
-    while (current && current !== PhotonMCP.prototype) {
+    while (current && current !== Photon.prototype) {
       Object.getOwnPropertyNames(current).forEach((name) => {
         // Skip private methods (starting with _) and convention methods
         if (

package/src/collections/Collection.ts

@@ -7,9 +7,9 @@
  *
  * @example
  * ```typescript
- * import { PhotonMCP, Collection } from '@portel/photon-core';
+ * import { Photon, Collection } from '@portel/photon-core';
  *
- * export default class ProductCatalog extends PhotonMCP {
+ * export default class ProductCatalog extends Photon {
  *   products = new Collection<Product>();
  *
  *   async catalog() {

package/src/compiler.ts

@@ -21,9 +21,9 @@ import * as crypto from 'crypto';
  * @returns Absolute path to the compiled .mjs file
  */
 /**
- * Transform arrays to reactive collections for PhotonMCP classes
+ * Transform arrays to reactive collections for Photon classes
  *
- * ZERO-EFFORT REACTIVITY: If a class extends PhotonMCP and has array properties,
+ * ZERO-EFFORT REACTIVITY: If a class extends Photon (or 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
@@ -32,23 +32,23 @@ import * as crypto from 'crypto';
  *
  * ```typescript
  * // Developer writes this (normal TypeScript):
- * export default class TodoList extends PhotonMCP {
+ * export default class TodoList extends Photon {
  *   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 {
+ * export default class TodoList extends Photon {
  *   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 this is a Photon class (extends Photon or extends PhotonMCP)
+  const isPhotonClass = /class\s+\w+\s+extends\s+(?:Photon|PhotonMCP)\b/.test(source);
+  if (!isPhotonClass) return source;
 
   // Check if there are array properties with = [] that need transformation
   // Look for patterns like: `items: Type[] = []` or `items = []` (class properties)

package/src/config.ts

@@ -8,7 +8,7 @@
  * ```typescript
  * import { loadPhotonConfig, savePhotonConfig, getPhotonConfigPath } from '@portel/photon-core';
  *
- * export default class MyPhoton extends PhotonMCP {
+ * export default class MyPhoton extends Photon {
  *   async configure(params: { apiKey: string }) {
  *     savePhotonConfig('my-photon', params);
  *     return { success: true, config: params };

package/src/index.ts

@@ -11,7 +11,7 @@
  *
  * @example
  * ```typescript
- * import { PhotonMCP, DependencyManager, SchemaExtractor } from '@portel/photon-core';
+ * import { Photon, DependencyManager, SchemaExtractor } from '@portel/photon-core';
  *
  * // Load and parse a Photon class
  * const photonClass = await import('./my-tool.photon.ts');
@@ -152,13 +152,13 @@ export {
 // ===== PHOTON-SPECIFIC EXPORTS =====
 
 // Core base class with lifecycle hooks
-export { PhotonMCP } from './base.js';
+export { Photon, Photon as PhotonMCP } from './base.js';
 
 // Dependency management
 export { DependencyManager } from './dependency-manager.js';
 
 // Schema extraction
-export { SchemaExtractor } from './schema-extractor.js';
+export { SchemaExtractor, detectCapabilities, type PhotonCapability } from './schema-extractor.js';
 
 // Path resolution (Photon-specific paths)
 export {
@@ -433,7 +433,7 @@ export {
 } from './audit.js';
 
 // ===== SCOPED MEMORY =====
-// Framework-level key-value storage (this.memory on PhotonMCP)
+// Framework-level key-value storage (this.memory on Photon base class)
 export {
   MemoryProvider,
   type MemoryScope,
@@ -446,6 +446,36 @@ export {
   autoDiscoverAssets,
 } from './asset-discovery.js';
 
+// ===== DURATION PARSING =====
+// Duration and rate string parsing for functional tags
+export { parseDuration, parseRate } from './utils/duration.js';
+
+// ===== EXTENSIBLE MIDDLEWARE =====
+// Registry-based middleware system for functional tags and custom middleware
+export {
+  defineMiddleware,
+  builtinRegistry,
+  MiddlewareRegistry,
+  createStateStore,
+  buildMiddlewareChain,
+  hashParams,
+  BUILT_IN_VALIDATORS,
+  type MiddlewareDefinition,
+  type MiddlewareContext,
+  type MiddlewareHandler,
+  type MiddlewareState,
+  type MiddlewareDeclaration,
+  type NextFn,
+} from './middleware.js';
+
+// ===== FILE WATCHING =====
+// Reusable photon file watcher with symlink resolution, debouncing, rename handling
+export { PhotonWatcher, type PhotonWatcherOptions } from './watcher.js';
+
+// ===== INSTANCE STORE =====
+// Named instance state persistence for daemon, NCP, Lumina
+export { InstanceStore, type InstanceStoreOptions } from './instance-store.js';
+
 // ===== MANAGED COLLECTIONS =====
 // Auto-emit events on mutations for seamless real-time sync
 export {