@portel/photon-core 2.15.0 → 2.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@portel/photon-core",
-  "version": "2.15.0",
+  "version": "2.17.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",

package/src/asset-discovery.ts

@@ -110,12 +110,32 @@ export async function autoDiscoverAssets(
   assets: PhotonAssets,
 ): Promise<void> {
   // Auto-discover UI files
+  // .photon.html files (declarative mode) take priority over .html files with the same base name.
   const uiDir = path.join(assetFolder, 'ui');
   if (await fileExists(uiDir)) {
     try {
       const files = await fs.readdir(uiDir);
+      // Collect .photon.html files first so they take priority
+      const photonHtmlFiles = new Set<string>();
       for (const file of files) {
-        const id = path.basename(file, path.extname(file));
+        if (file.endsWith('.photon.html')) {
+          photonHtmlFiles.add(file.replace(/\.photon\.html$/, ''));
+        }
+      }
+      for (const file of files) {
+        // Determine the asset ID:
+        // - foo.photon.html → id "foo"
+        // - foo.html → id "foo" (but skipped if foo.photon.html exists)
+        let id: string;
+        if (file.endsWith('.photon.html')) {
+          id = file.replace(/\.photon\.html$/, '');
+        } else {
+          id = path.basename(file, path.extname(file));
+          // Skip .html files when a .photon.html with the same base name exists
+          if (file.endsWith('.html') && photonHtmlFiles.has(id)) {
+            continue;
+          }
+        }
         if (!assets.ui.find((u) => u.id === id)) {
           assets.ui.push({
             id,

package/src/base.ts

@@ -40,7 +40,7 @@
  */
 
 import { MCPClient, MCPClientFactory, createMCPProxy } from '@portel/mcp';
-import { executionContext } from '@portel/cli';
+import { executionContext, type CallerInfo } from '@portel/cli';
 import { getBroker } from './channels/index.js';
 import { withLock as withLockHelper } from './decorators.js';
 import { MemoryProvider } from './memory.js';
@@ -95,6 +95,28 @@ export class Photon {
    */
   _sessionId?: string;
 
+  /**
+   * Authenticated caller identity
+   *
+   * Populated from MCP OAuth when `@auth` is enabled on the photon.
+   * Returns the identity of whoever is calling the current method —
+   * human (via social login) or agent (via API key).
+   *
+   * Returns an anonymous caller if no auth token was provided.
+   *
+   * @example
+   * ```typescript
+   * // In a method:
+   * const userId = this.caller.id;     // stable user ID from JWT
+   * const name = this.caller.name;     // display name
+   * const isAnon = this.caller.anonymous; // true if no auth
+   * ```
+   */
+  get caller(): CallerInfo {
+    const store = executionContext.getStore();
+    return store?.caller ?? { id: 'anonymous', anonymous: true };
+  }
+
   /**
    * Scoped key-value storage for photon data
    *
@@ -236,6 +258,33 @@ export class Photon {
     return path.join(dir, name, 'assets', subpath);
   }
 
+  /**
+   * Get a URL path for an asset served by Beam
+   *
+   * Returns a relative URL like `/api/assets/my-photon/images/logo.png`
+   * that Beam serves from the photon's assets directory. Use this in
+   * HTML, markdown, or slides where browser-accessible URLs are needed.
+   *
+   * @param subpath Path within the assets folder
+   * @returns URL path (relative to Beam host)
+   *
+   * @example
+   * ```typescript
+   * const logoUrl = this.assetUrl('images/logo.png');
+   * // → '/api/assets/my-photon/images/logo.png'
+   *
+   * return `![Logo](${logoUrl})`;  // works in markdown/slides
+   * ```
+   */
+  protected assetUrl(subpath: string): string {
+    const name = this._photonName || this.constructor.name
+      .replace(/MCP$/, '')
+      .replace(/([A-Z])/g, '-$1')
+      .toLowerCase()
+      .replace(/^-/, '');
+    return `/api/assets/${encodeURIComponent(name)}/${subpath}`;
+  }
+
   /**
    * Dynamic photon access
    *
@@ -457,16 +506,13 @@ export class Photon {
     ]);
 
     // Get all property names from prototype chain
+    // Use getOwnPropertyDescriptor to avoid triggering getters (which may call storage())
     let current = prototype;
     while (current && current !== Photon.prototype) {
       Object.getOwnPropertyNames(current).forEach((name) => {
-        // Skip private methods (starting with _) and convention methods
-        if (
-          !name.startsWith('_') &&
-          !conventionMethods.has(name) &&
-          typeof (prototype as any)[name] === 'function' &&
-          !methods.includes(name)
-        ) {
+        if (name.startsWith('_') || conventionMethods.has(name) || methods.includes(name)) return;
+        const desc = Object.getOwnPropertyDescriptor(current, name);
+        if (desc && typeof desc.value === 'function') {
           methods.push(name);
         }
       });
@@ -618,4 +664,106 @@ export class Photon {
   ): Promise<T> {
     return withLockHelper(lockName, fn, timeout);
   }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // IDENTITY-AWARE LOCK MANAGEMENT
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Identity-aware lock handler - injected by runtime
+   * @internal
+   */
+  _lockHandler?: {
+    assign(lockName: string, holder: string, timeout?: number): Promise<boolean>;
+    transfer(lockName: string, fromHolder: string, toHolder: string, timeout?: number): Promise<boolean>;
+    release(lockName: string, holder: string): Promise<boolean>;
+    query(lockName: string): Promise<{ holder: string | null; acquiredAt?: number; expiresAt?: number }>;
+  };
+
+  /**
+   * Assign a lock to a specific caller (identity-aware)
+   *
+   * Unlike `withLock` which auto-acquires/releases around a function,
+   * this explicitly assigns a lock to a caller ID. The lock persists
+   * until transferred or released.
+   *
+   * @param lockName Name of the lock
+   * @param callerId Caller ID to assign the lock to
+   * @param timeout Lock timeout in ms (default 30000, auto-extended on transfer)
+   *
+   * @example
+   * ```typescript
+   * // Assign "turn" lock to first player
+   * await this.acquireLock('turn', this.caller.id);
+   * ```
+   */
+  protected async acquireLock(lockName: string, callerId: string, timeout?: number): Promise<boolean> {
+    if (!this._lockHandler) {
+      console.warn(`[photon] acquireLock('${lockName}'): no lock handler configured`);
+      return true;
+    }
+    return this._lockHandler.assign(lockName, callerId, timeout);
+  }
+
+  /**
+   * Transfer a lock from the current holder to another caller
+   *
+   * Only succeeds if `fromCallerId` is the current holder.
+   *
+   * @param lockName Name of the lock
+   * @param toCallerId Caller ID to transfer the lock to
+   * @param fromCallerId Current holder (defaults to this.caller.id)
+   *
+   * @example
+   * ```typescript
+   * // After a chess move, transfer turn to opponent
+   * await this.transferLock('turn', opponentId);
+   * ```
+   */
+  protected async transferLock(lockName: string, toCallerId: string, fromCallerId?: string): Promise<boolean> {
+    if (!this._lockHandler) {
+      console.warn(`[photon] transferLock('${lockName}'): no lock handler configured`);
+      return true;
+    }
+    return this._lockHandler.transfer(lockName, fromCallerId ?? this.caller.id, toCallerId);
+  }
+
+  /**
+   * Release a lock (make the method open to anyone)
+   *
+   * @param lockName Name of the lock
+   * @param callerId Holder to release from (defaults to this.caller.id)
+   *
+   * @example
+   * ```typescript
+   * // Presenter releases navigation control to audience
+   * await this.releaseLock('navigation');
+   * ```
+   */
+  protected async releaseLock(lockName: string, callerId?: string): Promise<boolean> {
+    if (!this._lockHandler) {
+      console.warn(`[photon] releaseLock('${lockName}'): no lock handler configured`);
+      return true;
+    }
+    return this._lockHandler.release(lockName, callerId ?? this.caller.id);
+  }
+
+  /**
+   * Query who holds a specific lock
+   *
+   * @param lockName Name of the lock
+   * @returns Lock holder info, or null holder if unlocked
+   *
+   * @example
+   * ```typescript
+   * const lock = await this.getLock('turn');
+   * if (lock.holder === this.caller.id) { ... }
+   * ```
+   */
+  protected async getLock(lockName: string): Promise<{ holder: string | null; acquiredAt?: number; expiresAt?: number }> {
+    if (!this._lockHandler) {
+      return { holder: null };
+    }
+    return this._lockHandler.query(lockName);
+  }
 }

package/src/index.ts

@@ -74,6 +74,7 @@ export {
   executionContext,
   runWithContext,
   getContext,
+  type CallerInfo,
 
   // Text Utils
   TextUtils,

package/src/mixins.ts

@@ -23,7 +23,7 @@
  */
 
 import { MCPClient, MCPClientFactory, createMCPProxy } from '@portel/mcp';
-import { executionContext } from '@portel/cli';
+import { executionContext, type CallerInfo } from '@portel/cli';
 import { getBroker } from './channels/index.js';
 import { MemoryProvider } from './memory.js';
 import { ScheduleProvider } from './schedule.js';
@@ -94,6 +94,14 @@ export function withPhotonCapabilities<T extends Constructor>(Base: T): T {
      */
     private _mcpClients: Map<string, MCPClient & Record<string, (params?: any) => Promise<any>>> = new Map();
 
+    /**
+     * Authenticated caller identity from MCP OAuth
+     */
+    get caller(): CallerInfo {
+      const store = executionContext.getStore();
+      return store?.caller ?? { id: 'anonymous', anonymous: true };
+    }
+
     /**
      * Scoped key-value storage for photon data
      */

package/src/schema-extractor.ts

@@ -24,6 +24,13 @@ export interface ExtractedMetadata {
   configSchema?: ConfigSchema;
   /** Notification subscription from @notify-on tag */
   notificationSubscriptions?: NotificationSubscription;
+  /**
+   * MCP OAuth auth requirement (from @auth tag)
+   * - 'required': all methods require authenticated caller
+   * - 'optional': caller populated if token present, anonymous allowed
+   * - string URL: OIDC provider URL (implies required)
+   */
+  auth?: 'required' | 'optional' | string;
 }
 
 /**
@@ -64,6 +71,9 @@ export class SchemaExtractor {
     // Notification subscriptions tracking (from @notify-on tag)
     let notificationSubscriptions: NotificationSubscription | undefined;
 
+    // MCP OAuth auth requirement (from @auth tag)
+    let auth: 'required' | 'optional' | string | undefined;
+
     try {
       // If source doesn't contain a class declaration, wrap it in one
       let sourceToParse = source;
@@ -448,6 +458,12 @@ export class SchemaExtractor {
           const classJsdoc = this.getJSDocComment(node as any, sourceFile);
           const isStatefulClass = /@stateful\b/i.test(classJsdoc);
 
+          // Extract @auth tag for MCP OAuth requirement
+          const authMatch = classJsdoc.match(/@auth(?:\s+(\S+))?/i);
+          if (authMatch) {
+            auth = authMatch[1]?.trim() || 'required';
+          }
+
           // Extract notification subscriptions from @notify-on tag
           notificationSubscriptions = this.extractNotifyOn(classJsdoc);
 
@@ -495,6 +511,11 @@ export class SchemaExtractor {
       result.notificationSubscriptions = notificationSubscriptions;
     }
 
+    // Include auth requirement if detected
+    if (auth) {
+      result.auth = auth;
+    }
+
     return result;
   }
 
@@ -1220,7 +1241,7 @@ export class SchemaExtractor {
   private extractDescription(jsdocContent: string): string {
     // Split by @tags that appear at start of a JSDoc line (after optional * prefix)
     // This avoids matching @tag references inline in description text
-    const beforeTags = jsdocContent.split(/(?:^|\n)\s*\*?\s*@(?:param|example|returns?|throws?|see|since|deprecated|version|author|license|ui|icon|format|stateful|autorun|async|webhook|cron|scheduled|locked|fallback|logged|circuitBreaker|cached|timeout|retryable|throttled|debounced|queued|validate|use|Template|Static|mcp|photon|cli|tags|dependencies|csp|visibility)\b/)[0];
+    const beforeTags = jsdocContent.split(/(?:^|\n)\s*\*?\s*@(?:param|example|returns?|throws?|see|since|deprecated|version|author|license|ui|icon|format|stateful|autorun|async|webhook|cron|scheduled|locked|fallback|logged|circuitBreaker|cached|timeout|retryable|throttled|debounced|queued|validate|use|Template|Static|mcp|photon|cli|tags|dependencies|csp|visibility|auth)\b/)[0];
 
     // Remove leading * from each line and trim
     const lines = beforeTags
@@ -1387,11 +1408,23 @@ export class SchemaExtractor {
       if (formatMatch) {
         const format = formatMatch[1].trim();
         // Validate format is in whitelist (JSON Schema + custom formats)
-        const validFormats = ['email', 'date', 'date-time', 'time', 'duration', 'uri', 'uri-reference', 'uuid', 'ipv4', 'ipv6', 'hostname', 'json', 'table'];
-        if (!validFormats.includes(format)) {
+        const validFormats = [
+          // JSON Schema standard formats
+          'email', 'date', 'date-time', 'time', 'duration', 'uri', 'uri-reference', 'uuid', 'ipv4', 'ipv6', 'hostname',
+          // Photon display formats
+          'json', 'table', 'date-range', 'datetime-range',
+          // Enhanced input formats
+          'password', 'secret', 'url', 'phone', 'tel', 'search', 'color', 'textarea', 'slider',
+          'tags', 'rating', 'radio', 'segmented', 'code', 'markdown',
+          // File formats
+          'path', 'file', 'directory',
+        ];
+        // Allow subtypes like code:typescript, code:python
+        const formatBase = format.split(':')[0];
+        if (!validFormats.includes(format) && !validFormats.includes(formatBase)) {
           console.warn(
             `Invalid @format value: "${format}". ` +
-            `Valid formats: ${validFormats.join(', ')}. Format not applied.`
+            `Valid formats: ${validFormats.join(', ')} (with optional :subtype). Format not applied.`
           );
         } else {
           paramConstraints.format = format;
@@ -1619,7 +1652,13 @@ export class SchemaExtractor {
             `Pattern is ignored when specific values are defined via enum or @choice.`
           );
         }
-        // Skip enum types for most constraints (but still apply deprecated, examples, etc.)
+        // Skip enum types for most constraints (but still apply format, deprecated, examples, default)
+        if (constraints.format !== undefined) {
+          s.format = constraints.format;
+        }
+        if (constraints.default !== undefined) {
+          s.default = constraints.default;
+        }
         if (constraints.examples !== undefined) {
           s.examples = constraints.examples;
         }
@@ -2285,7 +2324,7 @@ export class SchemaExtractor {
     }
 
     // Match content formats
-    if (['json', 'markdown', 'yaml', 'xml', 'html', 'mermaid'].includes(format)) {
+    if (['json', 'markdown', 'yaml', 'xml', 'html', 'mermaid', 'embed'].includes(format)) {
       return format as OutputFormat;
     }
 
@@ -2300,7 +2339,14 @@ export class SchemaExtractor {
     }
 
     // Match visualization formats
-    if (['metric', 'gauge', 'timeline', 'dashboard', 'cart', 'qr'].includes(format)) {
+    if (['metric', 'gauge', 'progress', 'badge', 'timeline', 'dashboard', 'cart', 'qr', 'slides',
+         'steps', 'stepper', 'log', 'image', 'hero', 'banner', 'quote', 'profile', 'heatmap',
+         'kanban', 'calendar', 'map', 'cron', 'comparison', 'invoice', 'receipt', 'network', 'graph'].includes(format)) {
+      return format as OutputFormat;
+    }
+
+    // Match layout/design formats
+    if (['stat-group', 'statgroup', 'feature-grid', 'features', 'carousel', 'gallery', 'masonry'].includes(format)) {
       return format as OutputFormat;
     }
 
@@ -2920,7 +2966,7 @@ export class SchemaExtractor {
 /**
  * Capability types that can be auto-detected from source code
  */
-export type PhotonCapability = 'emit' | 'memory' | 'call' | 'mcp' | 'lock' | 'instanceMeta' | 'allInstances';
+export type PhotonCapability = 'emit' | 'memory' | 'call' | 'mcp' | 'lock' | 'instanceMeta' | 'allInstances' | 'caller';
 
 /**
  * Detect capabilities used by a Photon from its source code.
@@ -2941,5 +2987,6 @@ export function detectCapabilities(source: string): Set<PhotonCapability> {
   if (/this\.withLock\s*\(/.test(source)) caps.add('lock');
   if (/this\.instanceMeta\b/.test(source)) caps.add('instanceMeta');
   if (/this\.allInstances\s*\(/.test(source)) caps.add('allInstances');
+  if (/this\.caller\b/.test(source)) caps.add('caller');
   return caps;
 }

package/src/types.ts

@@ -7,11 +7,12 @@
  * - Structural: primitive, table, tree, list, none, card, grid, chips, kv
  * - Content: json, markdown, yaml, xml, html, mermaid, code, code:<lang>
  * - Visualization: chart, chart:<type>, metric, gauge, timeline, dashboard, cart
+ * - Content: json, markdown, yaml, xml, html, mermaid, code, code:<lang>, slides
  * - Container: panels, tabs, accordion, stack, columns
  */
 export type OutputFormat =
   | 'primitive' | 'table' | 'tree' | 'list' | 'none'
-  | 'json' | 'markdown' | 'yaml' | 'xml' | 'html' | 'mermaid'
+  | 'json' | 'markdown' | 'yaml' | 'xml' | 'html' | 'mermaid' | 'slides'
   | 'card' | 'grid' | 'chips' | 'kv' | 'qr'
   | 'chart' | `chart:${string}` | 'metric' | 'gauge' | 'timeline' | 'dashboard' | 'cart'
   | 'panels' | 'tabs' | 'accordion' | 'stack' | 'columns'