@portel/photon 1.32.5 → 1.33.0

package/dist/server.js

@@ -121,6 +121,83 @@ function uiSiblingMime(ext) {
             return 'application/octet-stream';
     }
 }
+function splitServerRoutePath(pathname) {
+    const normalized = pathname === '/' ? '/' : pathname.replace(/\/+$/, '');
+    if (normalized === '/')
+        return [];
+    return normalized.split('/').filter(Boolean);
+}
+function serverWebRouteMatches(routePath, requestPath) {
+    if (routePath === requestPath)
+        return true;
+    const routeParts = splitServerRoutePath(routePath);
+    const requestParts = splitServerRoutePath(requestPath);
+    if (routeParts.length !== requestParts.length)
+        return false;
+    for (let i = 0; i < routeParts.length; i++) {
+        const routePart = routeParts[i];
+        const requestPart = requestParts[i];
+        if (routePart.startsWith(':')) {
+            if (!requestPart)
+                return false;
+            continue;
+        }
+        if (routePart !== requestPart)
+            return false;
+    }
+    return true;
+}
+function serverWebRouteScore(routePath) {
+    return splitServerRoutePath(routePath).reduce((score, part) => score + (part.startsWith(':') ? 1 : 10), routePath === '/' ? 100 : 0);
+}
+function findServerWebRoute(routes, method, requestPath) {
+    if (!routes?.length || !method)
+        return undefined;
+    const wantedMethod = method.toUpperCase();
+    return routes
+        .filter((route) => route.method.toUpperCase() === wantedMethod &&
+        serverWebRouteMatches(route.path, requestPath))
+        .sort((a, b) => serverWebRouteScore(b.path) - serverWebRouteScore(a.path))[0];
+}
+function uiAssetPath(asset) {
+    return asset.resolvedPath || asset.path || '';
+}
+function isTsxUiAsset(asset) {
+    return uiAssetPath(asset).endsWith('.tsx');
+}
+function selectServerClientAppUi(photon) {
+    const uiAssets = photon?.assets?.ui || [];
+    const linkedUi = photon?.appEntry?.linkedUi;
+    if (linkedUi) {
+        const linkedAsset = uiAssets.find((ui) => ui.id === linkedUi);
+        if (!linkedAsset || isTsxUiAsset(linkedAsset))
+            return linkedUi;
+    }
+    const namedApp = uiAssets.find((ui) => ui.id === 'app' && isTsxUiAsset(ui));
+    if (namedApp)
+        return namedApp.id;
+    const tsxAssets = uiAssets.filter(isTsxUiAsset);
+    if (tsxAssets.length === 1)
+        return tsxAssets[0].id;
+    return undefined;
+}
+function selectServerWebAppUrl(photon) {
+    if (!photon?.name)
+        return undefined;
+    const hasWebRoot = photon._httpRoutes?.some((route) => route.method === 'GET' && route.path === '/');
+    if (!hasWebRoot && !selectServerClientAppUi(photon))
+        return undefined;
+    return `/web/${photon.name}/`;
+}
+function shouldFallbackToServerClientApp(pathname, searchParams, route) {
+    if (route)
+        return false;
+    if (searchParams.get('legacy') === '1')
+        return false;
+    if (pathname === '/mcp' || pathname.startsWith('/mcp/'))
+        return false;
+    return true;
+}
 function findFreePort(preferred = 0) {
     return new Promise((resolve, reject) => {
         const srv = createServer();
@@ -171,6 +248,12 @@ class BeamCompatTransport {
                 'x-photon-icon': this.photonMeta.icon || '⚡',
                 'x-photon-stateful': this.photonMeta.stateful || false,
                 'x-photon-has-settings': this.photonMeta.hasSettings || false,
+                ...(this.photonMeta.webUrl
+                    ? {
+                        'x-web-url': this.photonMeta.webUrl,
+                        'x-web-description': this.photonMeta.webDescription || this.photonMeta.description || '',
+                    }
+                    : {}),
             }));
             // Append sub-photon tools (each with their own x-photon-* metadata)
             for (const sub of this.subPhotons) {
@@ -183,6 +266,12 @@ class BeamCompatTransport {
                         'x-photon-icon': sub.icon,
                         'x-photon-stateful': sub.stateful,
                         'x-photon-has-settings': sub.hasSettings,
+                        ...(sub.webUrl
+                            ? {
+                                'x-web-url': sub.webUrl,
+                                'x-web-description': sub.webDescription || sub.description,
+                            }
+                            : {}),
                     };
                     // Add UI linking metadata if this tool has a linked UI
                     const meta = buildToolMCPMeta(tool, {
@@ -2140,6 +2229,62 @@ export class PhotonServer {
         }
         res.writeHead(404).end('Not Found');
     }
+    async serveTopLevelUiAsset(req, res, uiId, corsOrigin) {
+        const ui = this.mcp?.assets?.ui.find((asset) => asset.id === uiId);
+        if (!ui?.resolvedPath)
+            return false;
+        try {
+            // Non-.tsx assets: serve the file as-is (unchanged behaviour).
+            if (!ui.resolvedPath.endsWith('.tsx')) {
+                const content = await readText(ui.resolvedPath);
+                const uiHeaders = { 'Content-Type': 'text/html' };
+                if (corsOrigin)
+                    uiHeaders['Access-Control-Allow-Origin'] = corsOrigin;
+                if (detectIsolationMode(req) === 'standalone') {
+                    uiHeaders['Cross-Origin-Opener-Policy'] = 'same-origin';
+                    uiHeaders['Cross-Origin-Embedder-Policy'] = 'require-corp';
+                }
+                res.writeHead(200, uiHeaders);
+                res.end(content);
+                return true;
+            }
+            const { compileTsxCached, tsxHttpResponse } = await import('./tsx-compiler.js');
+            const compiled = await compileTsxCached(ui.resolvedPath);
+            // This mount doubles as the SPA fallback (any unmatched GET), so the
+            // browser's relative `./<hash>.js` request may arrive at an arbitrary
+            // depth. The hashed filename is unique, so match it by basename to
+            // serve the immutable bundle; everything else gets the shell.
+            const reqPath = (req.url ?? '').split('?')[0];
+            const lastSeg = decodeURIComponent(reqPath.slice(reqPath.lastIndexOf('/') + 1));
+            const restPath = compiled.jsFileName && lastSeg === compiled.jsFileName ? lastSeg : '';
+            const r = tsxHttpResponse(compiled, restPath);
+            // Cheap revalidation: 304 when the shell hash is unchanged.
+            const inm = req.headers['if-none-match'];
+            if (r.headers['ETag'] && inm && inm === r.headers['ETag']) {
+                const notMod = { ETag: r.headers['ETag'] };
+                if (corsOrigin)
+                    notMod['Access-Control-Allow-Origin'] = corsOrigin;
+                res.writeHead(304, notMod);
+                res.end();
+                return true;
+            }
+            const uiHeaders = { ...r.headers };
+            if (corsOrigin)
+                uiHeaders['Access-Control-Allow-Origin'] = corsOrigin;
+            if (!restPath && detectIsolationMode(req) === 'standalone') {
+                uiHeaders['Cross-Origin-Opener-Policy'] = 'same-origin';
+                uiHeaders['Cross-Origin-Embedder-Policy'] = 'require-corp';
+            }
+            if (restPath)
+                uiHeaders['Cross-Origin-Resource-Policy'] = 'same-origin';
+            res.writeHead(r.status, uiHeaders);
+            res.end(r.body);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     /**
      * Start server with SSE transport (HTTP)
      */
@@ -2156,11 +2301,15 @@ export class PhotonServer {
         let beamTransport = null;
         {
             const photonName = this.mcp?.name || 'photon';
+            const photonWebUrl = selectServerWebAppUrl(this.mcp);
             beamTransport = new BeamCompatTransport(photonName, {
                 description: this.mcp?.description,
                 icon: this.mcp?.icon,
                 stateful: !!this.mcp?.stateful,
                 hasSettings: !!this.mcp?.hasSettings,
+                ...(photonWebUrl
+                    ? { webUrl: photonWebUrl, webDescription: this.mcp?.description || `${photonName} MCP` }
+                    : {}),
             });
             this.capabilityNegotiator.interceptTransportForRawCapabilities(beamTransport, this.server, (msg) => this.channelManager.interceptPermissionRequest(msg));
             await this.server.connect(beamTransport);
@@ -2176,6 +2325,7 @@ export class PhotonServer {
                 // these two callsites still need the narrower runtime cast until
                 // the loader's return type widens to PhotonClassWithMeta.
                 const hasSettings = !!loaded.settingsSchema?.hasSettings;
+                const webUrl = selectServerWebAppUrl(loaded);
                 // Convert PhotonTool[] to MCP tool format with UI linking
                 const uiAssets = loaded.assets?.ui || [];
                 const tools = loaded.tools
@@ -2195,6 +2345,7 @@ export class PhotonServer {
                     icon,
                     stateful,
                     hasSettings,
+                    ...(webUrl ? { webUrl, webDescription: loaded.description || `${loaded.name} MCP` } : {}),
                     tools,
                 });
             }
@@ -2225,6 +2376,11 @@ export class PhotonServer {
                 }
                 const url = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
                 const corsOrigin = getCorsOrigin(req);
+                let matchedRoute = null;
+                const route = findServerWebRoute(this.mcp?._httpRoutes, req.method, url.pathname);
+                if (route)
+                    matchedRoute = { handler: route.handler, format: route.format };
+                const clientAppUi = selectServerClientAppUi(this.mcp);
                 // Handle CORS preflight
                 if (req.method === 'OPTIONS') {
                     const preflightHeaders = {
@@ -2262,7 +2418,7 @@ export class PhotonServer {
                     return;
                 }
                 // Health check / info endpoint
-                if (req.method === 'GET' && url.pathname === '/') {
+                if (req.method === 'GET' && url.pathname === '/' && !matchedRoute && !clientAppUi) {
                     res.writeHead(200, { 'Content-Type': 'application/json' });
                     const endpoints = {
                         sse: `http://localhost:${port}${ssePath}`,
@@ -2529,14 +2685,31 @@ export class PhotonServer {
                         }
                         if (ui?.resolvedPath) {
                             try {
-                                let content;
                                 if (ui.resolvedPath.endsWith('.tsx')) {
-                                    const { compileTsxCached } = await import('./tsx-compiler.js');
-                                    content = await compileTsxCached(ui.resolvedPath);
-                                }
-                                else {
-                                    content = await readText(ui.resolvedPath);
+                                    const { compileTsxCached, tsxHttpResponse } = await import('./tsx-compiler.js');
+                                    const compiled = await compileTsxCached(ui.resolvedPath);
+                                    const r = tsxHttpResponse(compiled, '');
+                                    const inm = req.headers['if-none-match'];
+                                    if (r.headers['ETag'] && inm && inm === r.headers['ETag']) {
+                                        const notMod = { ETag: r.headers['ETag'] };
+                                        if (corsOrigin)
+                                            notMod['Access-Control-Allow-Origin'] = corsOrigin;
+                                        res.writeHead(304, notMod);
+                                        res.end();
+                                        return;
+                                    }
+                                    const tsxHeaders = { ...r.headers };
+                                    if (corsOrigin)
+                                        tsxHeaders['Access-Control-Allow-Origin'] = corsOrigin;
+                                    if (detectIsolationMode(req) === 'standalone') {
+                                        tsxHeaders['Cross-Origin-Opener-Policy'] = 'same-origin';
+                                        tsxHeaders['Cross-Origin-Embedder-Policy'] = 'require-corp';
+                                    }
+                                    res.writeHead(r.status, tsxHeaders);
+                                    res.end(r.body);
+                                    return;
                                 }
+                                const content = await readText(ui.resolvedPath);
                                 const uiHeaders = { 'Content-Type': 'text/html' };
                                 if (corsOrigin)
                                     uiHeaders['Access-Control-Allow-Origin'] = corsOrigin;
@@ -2560,6 +2733,25 @@ export class PhotonServer {
                         res.writeHead(404).end('UI not found');
                         return;
                     }
+                    // Compiled .tsx bundle: the shell references `./<base>.<hash>.js`,
+                    // which lands here as a sub-path. Serve it from the compile cache
+                    // with an immutable cache policy (the hash is the cache key).
+                    if (ui?.resolvedPath?.endsWith('.tsx')) {
+                        const { compileTsxCached, tsxHttpResponse } = await import('./tsx-compiler.js');
+                        const compiled = await compileTsxCached(ui.resolvedPath);
+                        const r = tsxHttpResponse(compiled, restPath);
+                        if (r.status === 200) {
+                            const jsHeaders = { ...r.headers };
+                            if (corsOrigin)
+                                jsHeaders['Access-Control-Allow-Origin'] = corsOrigin;
+                            jsHeaders['Cross-Origin-Resource-Policy'] = 'same-origin';
+                            res.writeHead(200, jsHeaders);
+                            res.end(r.body);
+                            return;
+                        }
+                        // Not the bundle (e.g. a static sibling shipped beside the .tsx) —
+                        // fall through to filesystem resolution below.
+                    }
                     // Sub-path: directory-style sibling resolution. Try the filesystem
                     // first (dev mode), then the embedded asset tree (compiled binary).
                     if (ui?.resolvedPath) {
@@ -2733,13 +2925,6 @@ export class PhotonServer {
                 // @get / @post HTTP routes — dispatch to photon method, public (no auth).
                 // Track C: when none match, fall through to the auto-RPC table built
                 // from @expose tags below.
-                const httpRoutes = this.mcp?._httpRoutes;
-                let matchedRoute = null;
-                if (httpRoutes?.length && req.method) {
-                    const route = httpRoutes.find((r) => r.method === req.method && r.path === url.pathname);
-                    if (route)
-                        matchedRoute = { handler: route.handler, format: route.format };
-                }
                 // Track C: auto-RPC. POST /api/<kebab-method> dispatches to @expose'd
                 // methods. Explicit @get/@post takes precedence (matchedRoute already
                 // set above) so a user can override path/verb for any @expose'd
@@ -2871,6 +3056,13 @@ export class PhotonServer {
                         return;
                     }
                 }
+                if (req.method === 'GET' &&
+                    clientAppUi &&
+                    shouldFallbackToServerClientApp(url.pathname, url.searchParams, matchedRoute ?? undefined)) {
+                    const served = await this.serveTopLevelUiAsset(req, res, clientAppUi, corsOrigin);
+                    if (served)
+                        return;
+                }
                 res.writeHead(404).end('Not Found');
             })();
         });