@portel/photon-core 2.14.0 → 2.15.0

package/src/generator.ts

@@ -730,6 +730,23 @@ export interface EmitQR {
   value: string;
 }
 
+/**
+ * Render emit — sends a formatted intermediate result to the client.
+ * The value is rendered using the same format pipeline as @format return values.
+ * Custom formats are resolved from assets/formats/<name>.html.
+ */
+export interface EmitRender {
+  emit: 'render';
+  /** Format type (table, qr, chart:bar, dashboard, or custom name) */
+  format: string;
+  /** Data to render — same shape as a return value with that @format */
+  value: any;
+}
+
+export interface EmitRenderClear {
+  emit: 'render:clear';
+}
+
 export type EmitYield =
   | EmitStatus
   | EmitProgress
@@ -739,7 +756,9 @@ export type EmitYield =
   | EmitThinking
   | EmitArtifact
   | EmitUI
-  | EmitQR;
+  | EmitQR
+  | EmitRender
+  | EmitRenderClear;
 
 // ══════════════════════════════════════════════════════════════════════════════
 // COMBINED TYPES

package/src/index.ts

@@ -166,12 +166,15 @@ export { SchemaExtractor, detectCapabilities, type PhotonCapability } from './sc
 export {
   resolvePath,
   listFiles,
+  listFilesWithNamespace,
   ensureDir,
   resolvePhotonPath,
   listPhotonFiles,
+  listPhotonFilesWithNamespace,
   ensurePhotonDir,
   DEFAULT_PHOTON_DIR,
   type ResolverOptions,
+  type ListedPhoton,
 } from './path-resolver.js';
 
 // Types
@@ -239,6 +242,8 @@ export {
   type EmitArtifact,
   type EmitUI,
   type EmitQR,
+  type EmitRender,
+  type EmitRenderClear,
 
   // Checkpoint yield type
   type CheckpointYield,

package/src/mixins.ts

@@ -124,6 +124,18 @@ export function withPhotonCapabilities<T extends Constructor>(Base: T): T {
       return this._schedule;
     }
 
+    /**
+     * Render a formatted value as an intermediate result.
+     * Each call replaces the previous render. Call with no args to clear.
+     */
+    protected render(format?: string, value?: any): void {
+      if (format === undefined) {
+        this.emit({ emit: 'render:clear' });
+      } else {
+        this.emit({ emit: 'render', format, value });
+      }
+    }
+
     /**
      * Emit an event/progress update
      */
@@ -139,9 +151,15 @@ export function withPhotonCapabilities<T extends Constructor>(Base: T): T {
       }
 
       if (data && typeof data.channel === 'string') {
+        // Auto-prefix channel with photon name if not already namespaced
+        const channel = data.channel.includes(':')
+          ? data.channel
+          : this._photonName
+            ? `${this._photonName}:${data.channel}`
+            : data.channel;
         const broker = getBroker();
         broker.publish({
-          channel: data.channel,
+          channel,
           event: data.event || 'message',
           data: data.data !== undefined ? data.data : data,
           timestamp: Date.now(),

package/src/path-resolver.ts

@@ -3,6 +3,14 @@
  *
  * Generic path resolution utilities used by photon, lumina, ncp.
  * Configurable file extensions and default directories.
+ *
+ * Supports namespace-based directory structure:
+ *   ~/.photon/
+ *     portel-dev/          ← namespace (marketplace author)
+ *       whatsapp.photon.ts
+ *     local/               ← implicit namespace for user-created photons
+ *       todo.photon.ts
+ *     legacy.photon.ts     ← flat files (pre-migration, still supported)
  */
 
 import * as fs from 'fs/promises';
@@ -37,9 +45,17 @@ const defaultOptions: Required<ResolverOptions> = {
   defaultDir: DEFAULT_PHOTON_DIR,
 };
 
+/** Directories to skip when scanning for namespace subdirectories */
+const SKIP_DIRS = new Set([
+  'state', 'context', 'env', '.cache', '.config',
+  'node_modules', 'marketplace', 'photons', 'templates',
+]);
+
 /**
- * Resolve a file path from name
- * Looks in the specified working directory, or uses absolute path if provided
+ * Resolve a file path from name.
+ *
+ * Supports namespace-qualified names: 'namespace:photonName'
+ * For unqualified names, searches flat files first, then namespace subdirectories.
  */
 export async function resolvePath(
   name: string,
@@ -59,66 +75,172 @@ export async function resolvePath(
     }
   }
 
+  // Parse namespace:name format
+  const colonIndex = name.indexOf(':');
+  let namespace: string | undefined;
+  let photonName: string;
+  if (colonIndex !== -1) {
+    namespace = name.slice(0, colonIndex);
+    photonName = name.slice(colonIndex + 1);
+  } else {
+    photonName = name;
+  }
+
   // Remove extension if provided (match any configured extension)
-  let basename = name;
+  let basename = photonName;
   for (const ext of opts.extensions) {
-    if (name.endsWith(ext)) {
-      basename = name.slice(0, -ext.length);
+    if (photonName.endsWith(ext)) {
+      basename = photonName.slice(0, -ext.length);
       break;
     }
   }
 
-  // Try each extension
+  // If namespace is specified, search only that namespace directory
+  if (namespace) {
+    for (const ext of opts.extensions) {
+      const filePath = path.join(dir, namespace, `${basename}${ext}`);
+      try {
+        await fs.access(filePath);
+        return filePath;
+      } catch {
+        // Continue
+      }
+    }
+    return null;
+  }
+
+  // Unqualified name: search flat files first (backward compat)
   for (const ext of opts.extensions) {
     const filePath = path.join(dir, `${basename}${ext}`);
     try {
       await fs.access(filePath);
       return filePath;
     } catch {
-      // Continue to next extension
+      // Continue
+    }
+  }
+
+  // Then search namespace subdirectories (one level deep)
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory() || SKIP_DIRS.has(entry.name) || entry.name.startsWith('.')) {
+        continue;
+      }
+      for (const ext of opts.extensions) {
+        const filePath = path.join(dir, entry.name, `${basename}${ext}`);
+        try {
+          await fs.access(filePath);
+          return filePath;
+        } catch {
+          // Continue
+        }
+      }
     }
+  } catch {
+    // dir doesn't exist
   }
 
-  // Not found
   return null;
 }
 
 /**
- * List all matching files in a directory
+ * Result from listing files, including namespace information.
+ */
+export interface ListedPhoton {
+  /** Short name (e.g., 'whatsapp') */
+  name: string;
+  /** Namespace (e.g., 'portel-dev') or empty string for flat/root-level files */
+  namespace: string;
+  /** Qualified name (e.g., 'portel-dev:whatsapp' or 'whatsapp' for flat) */
+  qualifiedName: string;
+  /** Full absolute path to the file */
+  filePath: string;
+}
+
+/**
+ * List all matching files in a directory.
+ *
+ * Scans both flat files (backward compat) and namespace subdirectories.
+ * Returns short names for backward compatibility.
  */
 export async function listFiles(
   workingDir?: string,
   options?: ResolverOptions
 ): Promise<string[]> {
+  const listed = await listFilesWithNamespace(workingDir, options);
+  return listed.map((l) => l.name).sort();
+}
+
+/**
+ * List all matching files with full namespace metadata.
+ *
+ * Scans flat files at the root level and one level of namespace subdirectories.
+ */
+export async function listFilesWithNamespace(
+  workingDir?: string,
+  options?: ResolverOptions
+): Promise<ListedPhoton[]> {
   const opts = { ...defaultOptions, ...options };
   const dir = expandTilde(workingDir || opts.defaultDir);
+  const results: ListedPhoton[] = [];
 
   try {
-    // Ensure directory exists
     await fs.mkdir(dir, { recursive: true });
-
     const entries = await fs.readdir(dir, { withFileTypes: true });
-    const files: string[] = [];
 
+    // Scan flat files at root level (backward compat / pre-migration)
     for (const entry of entries) {
-      // Include both regular files and symlinks
       if (entry.isFile() || entry.isSymbolicLink()) {
-        // Check if file matches any extension
         for (const ext of opts.extensions) {
           if (entry.name.endsWith(ext)) {
-            // Remove extension for display
             const name = entry.name.slice(0, -ext.length);
-            files.push(name);
+            results.push({
+              name,
+              namespace: '',
+              qualifiedName: name,
+              filePath: path.join(dir, entry.name),
+            });
             break;
           }
         }
       }
     }
 
-    return files.sort();
+    // Scan namespace subdirectories (one level deep)
+    for (const entry of entries) {
+      if (!entry.isDirectory() || SKIP_DIRS.has(entry.name) || entry.name.startsWith('.')) {
+        continue;
+      }
+
+      const nsDir = path.join(dir, entry.name);
+      try {
+        const nsEntries = await fs.readdir(nsDir, { withFileTypes: true });
+        for (const nsEntry of nsEntries) {
+          if (nsEntry.isFile() || nsEntry.isSymbolicLink()) {
+            for (const ext of opts.extensions) {
+              if (nsEntry.name.endsWith(ext)) {
+                const name = nsEntry.name.slice(0, -ext.length);
+                results.push({
+                  name,
+                  namespace: entry.name,
+                  qualifiedName: `${entry.name}:${name}`,
+                  filePath: path.join(nsDir, nsEntry.name),
+                });
+                break;
+              }
+            }
+          }
+        }
+      } catch {
+        // Namespace dir unreadable, skip
+      }
+    }
   } catch {
-    return [];
+    // Root dir doesn't exist
   }
+
+  return results;
 }
 
 /**
@@ -132,4 +254,5 @@ export async function ensureDir(dir?: string): Promise<void> {
 // Convenience aliases for photon-specific usage
 export const resolvePhotonPath = resolvePath;
 export const listPhotonFiles = listFiles;
+export const listPhotonFilesWithNamespace = listFilesWithNamespace;
 export const ensurePhotonDir = ensureDir;

package/src/photon-loader-lite.ts

@@ -368,7 +368,7 @@ function wrapStatefulMethods(
 
   // Skip framework-injected methods from withPhotonCapabilities
   const frameworkMethods = new Set([
-    'emit', 'call', 'mcp', 'setMCPFactory', 'onInitialize', 'onShutdown',
+    'emit', 'render', 'call', 'mcp', 'setMCPFactory', 'onInitialize', 'onShutdown',
   ]);
 
   // Walk the prototype chain to find all public methods

package/src/schema-extractor.ts

@@ -1329,6 +1329,7 @@ export class SchemaExtractor {
         .replace(/\{@pattern\s+[^}]+\}/g, '')
         .replace(/\{@format\s+[^}]+\}/g, '')
         .replace(/\{@choice\s+[^}]+\}/g, '')
+        .replace(/\{@choice-from\s+[^}]+\}/g, '')
         .replace(/\{@field\s+[^}]+\}/g, '')
         .replace(/\{@default\s+[^}]+\}/g, '')
         .replace(/\{@unique(?:Items)?\s*\}/g, '')
@@ -1404,6 +1405,12 @@ export class SchemaExtractor {
         paramConstraints.enum = choices;
       }
 
+      // Extract {@choice-from toolName} or {@choice-from toolName.field}
+      const choiceFromMatch = description.match(/\{@choice-from\s+([^}]+)\}/);
+      if (choiceFromMatch) {
+        paramConstraints.choiceFrom = choiceFromMatch[1].trim();
+      }
+
       // Extract {@field type} - hints for UI form rendering
       const fieldMatch = description.match(/\{@field\s+([a-z]+)\}/);
       if (fieldMatch) {
@@ -1526,7 +1533,7 @@ export class SchemaExtractor {
       }
 
       // Validate no unknown {@...} tags (typos in constraint names)
-      const allKnownTags = ['min', 'max', 'pattern', 'format', 'choice', 'field', 'default', 'unique', 'uniqueItems',
+      const allKnownTags = ['min', 'max', 'pattern', 'format', 'choice', 'choice-from', 'field', 'default', 'unique', 'uniqueItems',
                              'example', 'multipleOf', 'deprecated', 'readOnly', 'writeOnly', 'label', 'placeholder',
                              'hint', 'hidden', 'accept', 'minItems', 'maxItems'];
       const unknownTagRegex = /\{@([\w-]+)\s*(?:\s+[^}]*)?\}/g;
@@ -1715,6 +1722,10 @@ export class SchemaExtractor {
           s.enum = constraints.enum;
         }
       }
+      // Apply dynamic choice provider (x-choiceFrom extension)
+      if (constraints.choiceFrom !== undefined) {
+        s['x-choiceFrom'] = constraints.choiceFrom;
+      }
       // Apply field hint for UI rendering
       if (constraints.field !== undefined) {
         s.field = constraints.field;
@@ -2652,7 +2663,7 @@ export class SchemaExtractor {
         };
       }
 
-      // Check if matches an @photon declaration
+      // Check if matches an @photon declaration (exact match)
       if (photonMap.has(param.name)) {
         return {
           param,
@@ -2661,6 +2672,25 @@ export class SchemaExtractor {
         };
       }
 
+      // Instance-aware DI: if paramName ends with a photon dep name (case-insensitive),
+      // the prefix becomes the instance name.
+      // e.g., personalWhatsapp + @photon whatsapp → instance "personal" of whatsapp
+      //       workWhatsapp + @photon whatsapp → instance "work" of whatsapp
+      for (const [depName, dep] of photonMap) {
+        const lowerParam = param.name.toLowerCase();
+        const lowerDep = depName.toLowerCase();
+        if (lowerParam.endsWith(lowerDep) && lowerParam.length > lowerDep.length) {
+          const prefix = param.name.slice(0, param.name.length - depName.length);
+          // Ensure the prefix is a valid instance name (lowercase the first char)
+          const instanceName = prefix.charAt(0).toLowerCase() + prefix.slice(1);
+          return {
+            param,
+            injectionType: 'photon' as const,
+            photonDependency: { ...dep, instanceName: instanceName || undefined },
+          };
+        }
+      }
+
       // Non-primitive with default on @stateful class → persisted state
       if (isStateful && param.hasDefault) {
         return {
@@ -2826,7 +2856,15 @@ export class SchemaExtractor {
                 // Link UI asset to this method
                 const asset = uiAssets.find(a => a.id === uiId);
                 if (asset) {
-                  asset.linkedTool = methodName;
+                  // First method wins as primary (used for app detection)
+                  if (!asset.linkedTool) {
+                    asset.linkedTool = methodName;
+                  }
+                  // Track all methods that reference this UI
+                  if (!asset.linkedTools) asset.linkedTools = [];
+                  if (!asset.linkedTools.includes(methodName)) {
+                    asset.linkedTools.push(methodName);
+                  }
                 }
               }
             }
@@ -2896,6 +2934,7 @@ export type PhotonCapability = 'emit' | 'memory' | 'call' | 'mcp' | 'lock' | 'in
 export function detectCapabilities(source: string): Set<PhotonCapability> {
   const caps = new Set<PhotonCapability>();
   if (/this\.emit\s*\(/.test(source)) caps.add('emit');
+  if (/this\.render\s*\(/.test(source)) caps.add('emit'); // render() needs emit injection
   if (/this\.memory\b/.test(source)) caps.add('memory');
   if (/this\.call\s*\(/.test(source)) caps.add('call');
   if (/this\.mcp\s*\(/.test(source)) caps.add('mcp');

package/src/types.ts

@@ -432,8 +432,10 @@ export interface UIAsset {
   resolvedPath?: string;
   /** MIME type (detected from extension) */
   mimeType?: string;
-  /** Tool this UI is linked to (from method @ui annotation) */
+  /** Primary tool this UI is linked to (first method with @ui annotation — used for app detection) */
   linkedTool?: string;
+  /** All tools that reference this UI asset (multiple methods can share one template) */
+  linkedTools?: string[];
   /** MCP resource URI (set by loader, e.g., 'ui://photon-name/main-ui') */
   uri?: string;
 }