hyperframes/packages/cli/src/server/studioServer.ts

/**
 * Embedded studio server for `hyperframes preview` outside the monorepo.
 *
 * Uses the shared studio API module from @hyperframes/core/studio-api,
 * providing a CLI-specific adapter for single-project, in-process rendering.
 */

import { Hono, type Context } from "hono";
import { streamSSE } from "hono/streaming";
import { existsSync, readFileSync, writeFileSync, statSync } from "node:fs";
import { resolve, join, basename } from "node:path";
import { createProjectWatcher, type ProjectWatcher } from "./fileWatcher.js";
import { loadRuntimeSource } from "./runtimeSource.js";
import { VERSION as version } from "../version.js";
import {
  createStudioApi,
  createProjectSignature,
  getMimeType,
  type StudioApiAdapter,
  type ResolvedProject,
  type RenderJobState,
} from "@hyperframes/core/studio-api";
import { getElementScreenshotClip } from "@hyperframes/core/studio-api/screenshot-clip";
import type { ScreenshotClip } from "@hyperframes/core/studio-api/screenshot-clip";

// ── Path resolution ─────────────────────────────────────────────────────────

function resolveDistDir(): string {
  return resolveStudioBundle().dir;
}

export interface StudioBundleResolution {
  dir: string;
  indexPath: string;
  available: boolean;
  checkedPaths: string[];
}

export function resolveStudioBundle(): StudioBundleResolution {
  const builtPath = resolve(__dirname, "studio");
  const builtIndex = resolve(builtPath, "index.html");
  if (existsSync(builtIndex)) {
    return { dir: builtPath, indexPath: builtIndex, available: true, checkedPaths: [builtIndex] };
  }
  const devPath = resolve(__dirname, "..", "..", "..", "studio", "dist");
  const devIndex = resolve(devPath, "index.html");
  if (existsSync(devIndex)) {
    return {
      dir: devPath,
      indexPath: devIndex,
      available: true,
      checkedPaths: [builtIndex, devIndex],
    };
  }
  return {
    dir: builtPath,
    indexPath: builtIndex,
    available: false,
    checkedPaths: [builtIndex, devIndex],
  };
}

function resolveRuntimePath(): string {
  const builtPath = resolve(__dirname, "hyperframe-runtime.js");
  if (existsSync(builtPath)) return builtPath;
  const iifePath = resolve(__dirname, "hyperframe.runtime.iife.js");
  if (existsSync(iifePath)) return iifePath;
  const devPath = resolve(
    __dirname,
    "..",
    "..",
    "..",
    "core",
    "dist",
    "hyperframe.runtime.iife.js",
  );
  if (existsSync(devPath)) return devPath;
  return builtPath;
}

// ── Shared thumbnail browser (singleton per process) ────────────────────────
// One browser instance is reused across all composition thumbnail requests.
// Spawning a new Puppeteer process per request adds 2-5s overhead and causes
// contention when the sidebar requests multiple thumbnails simultaneously.

let _thumbnailBrowser: import("puppeteer-core").Browser | null = null;
let _thumbnailBrowserInitializing: Promise<import("puppeteer-core").Browser | null> | null = null;

async function getThumbnailBrowser(): Promise<import("puppeteer-core").Browser | null> {
  if (_thumbnailBrowser?.connected) return _thumbnailBrowser;
  if (_thumbnailBrowserInitializing) return _thumbnailBrowserInitializing;

  _thumbnailBrowserInitializing = (async () => {
    try {
      const { ensureBrowser } = await import("../browser/manager.js");
      const { acquireBrowser, buildChromeArgs } = await import("@hyperframes/engine");

      try {
        const b = await ensureBrowser();
        if (b.executablePath && !process.env.PRODUCER_HEADLESS_SHELL_PATH) {
          process.env.PRODUCER_HEADLESS_SHELL_PATH = b.executablePath;
        }
      } catch {
        /* continue — acquireBrowser will try its own resolution */
      }

      const acquired = await acquireBrowser(buildChromeArgs({ width: 1920, height: 1080 }), {
        enableBrowserPool: false,
      });
      _thumbnailBrowser = acquired.browser;
      _thumbnailBrowser.on("disconnected", () => {
        _thumbnailBrowser = null;
        _thumbnailBrowserInitializing = null;
      });
      return _thumbnailBrowser;
    } catch {
      _thumbnailBrowserInitializing = null;
      return null;
    }
  })();

  return _thumbnailBrowserInitializing;
}

// ── Server factory ──────────────────────────────────────────────────────────

export interface StudioServerOptions {
  projectDir: string;
  /** Display name for the project. Defaults to basename of projectDir. */
  projectName?: string;
}

export interface StudioServer {
  app: Hono;
  watcher: ProjectWatcher;
}

export function createStudioServer(options: StudioServerOptions): StudioServer {
  const { projectDir, projectName } = options;
  const projectId = projectName || basename(projectDir);
  const studioDir = resolveDistDir();
  const runtimePath = resolveRuntimePath();
  const watcher = createProjectWatcher(projectDir);

  // ── CLI adapter for the shared studio API ──────────────────────────────

  const project: ResolvedProject = { id: projectId, dir: projectDir, title: projectId };
  let cachedProjectSignature: string | null = null;
  watcher.addListener(() => {
    cachedProjectSignature = null;
  });

  const adapter: StudioApiAdapter = {
    listProjects: () => [project],

    resolveProject: (id: string) => (id === projectId ? project : null),

    async bundle(dir: string): Promise<string | null> {
      try {
        const { bundleToSingleHtml } = await import("@hyperframes/core/compiler");
        // Studio dev server: ask the bundler for an empty `src=""` placeholder so
        // we can point it at our hot-reloadable local runtime endpoint. Inlining
        // ~150 KB of runtime body on every preview render would defeat browser
        // caching across composition edits.
        let html = await bundleToSingleHtml(dir, { runtime: "placeholder" });
        html = html.replace(
          'data-hyperframes-preview-runtime="1" src=""',
          'data-hyperframes-preview-runtime="1" src="/api/runtime.js"',
        );
        return html;
      } catch (err) {
        console.error("[studio] Bundle failed:", err);
        return null;
      }
    },

    getProjectSignature(dir: string): string {
      if (resolve(dir) !== resolve(projectDir)) return createProjectSignature(dir);
      cachedProjectSignature ??= createProjectSignature(projectDir);
      return cachedProjectSignature;
    },

    async lint(html: string, opts?: { filePath?: string }) {
      const { lintHyperframeHtml } = await import("@hyperframes/core/lint");
      return lintHyperframeHtml(html, opts);
    },

    runtimeUrl: "/api/runtime.js",

    rendersDir: () => join(projectDir, "renders"),

    startRender(opts): RenderJobState {
      const state: RenderJobState = {
        id: opts.jobId,
        status: "rendering",
        progress: 0,
        outputPath: opts.outputPath,
      };

      // Run render asynchronously, mutating the state object
      (async () => {
        try {
          const { createRenderJob, executeRenderJob } = await import("@hyperframes/producer");
          const { ensureBrowser } = await import("../browser/manager.js");

          try {
            const browser = await ensureBrowser();
            if (browser.executablePath && !process.env.PRODUCER_HEADLESS_SHELL_PATH) {
              process.env.PRODUCER_HEADLESS_SHELL_PATH = browser.executablePath;
            }
          } catch {
            // Continue without — acquireBrowser will try its own resolution
          }

          const job = createRenderJob({
            fps: opts.fps as 24 | 30 | 60,
            quality: opts.quality as "draft" | "standard" | "high",
            format: opts.format,
            outputResolution: opts.outputResolution,
          });
          const startTime = Date.now();
          const onProgress = (j: { progress: number; currentStage?: string }) => {
            state.progress = j.progress;
            if (j.currentStage) state.stage = j.currentStage;
          };
          await executeRenderJob(job, opts.project.dir, opts.outputPath, onProgress);
          state.status = "complete";
          state.progress = 100;
          const metaPath = opts.outputPath.replace(/\.(mp4|webm|mov)$/, ".meta.json");
          writeFileSync(
            metaPath,
            JSON.stringify({ status: "complete", durationMs: Date.now() - startTime }),
          );
        } catch (err) {
          state.status = "failed";
          state.error = err instanceof Error ? err.message : String(err);
          try {
            const metaPath = opts.outputPath.replace(/\.(mp4|webm|mov)$/, ".meta.json");
            writeFileSync(metaPath, JSON.stringify({ status: "failed" }));
          } catch {
            /* ignore */
          }
        }
      })();

      return state;
    },

    async generateThumbnail(opts): Promise<Buffer | null> {
      // Reuse a single browser across all thumbnail requests for this server
      // instance — avoids paying the ~2s Puppeteer startup cost per composition.
      // The browser is created lazily and kept alive until the process exits.
      const browser = await getThumbnailBrowser();
      if (!browser) return null;
      let page: import("puppeteer-core").Page | null = null;
      try {
        page = await browser.newPage();
        await page.setViewport({ width: opts.width || 1920, height: opts.height || 1080 });
        // domcontentloaded instead of networkidle2 — CDN scripts (GSAP, Lottie,
        // fonts) never reach "idle" and cause a 15s timeout per thumbnail.
        await page.goto(opts.previewUrl, { waitUntil: "domcontentloaded", timeout: 10000 });
        // Wait for the runtime to register timelines (up to 5s, non-fatal).
        await page
          .waitForFunction(() => !!(window as any).__timelines || !!(window as any).__playerReady, {
            timeout: 5000,
          })
          .catch(() => {});
        await page.evaluate((t: number) => {
          const win = window as any;
          if (win.__player?.seek) win.__player.seek(t);
          else if (win.__timeline?.seek) {
            win.__timeline.pause();
            win.__timeline.seek(t);
          }
        }, opts.seekTime);
        // Let the seek render settle.
        await new Promise((r) => setTimeout(r, 200));
        let clip: ScreenshotClip | undefined;
        if (opts.selector) {
          clip = await page.evaluate(getElementScreenshotClip, opts.selector);
        }
        const screenshot = (await page.screenshot(
          opts.format === "png"
            ? {
                type: "png",
                ...(clip ? { clip } : {}),
              }
            : {
                type: "jpeg",
                quality: 80,
                ...(clip ? { clip } : {}),
              },
        )) as Buffer;
        return screenshot;
      } catch {
        return null;
      } finally {
        await page?.close().catch(() => {});
      }
    },
  };

  // ── Build the Hono app ─────────────────────────────────────────────────

  const app = new Hono();

  // Config probe endpoint — used by port detection to identify existing
  // HyperFrames instances and reuse them instead of spawning duplicates.
  // See portUtils.ts detectHyperframesServer() for the consumer.
  app.get("/__hyperframes_config", (c) => {
    return c.json({
      isHyperframes: true,
      projectName: projectId,
      projectDir: projectDir,
      version,
    });
  });

  // CLI-specific routes (before shared API)
  app.get("/api/runtime.js", (c) => {
    const serve = async () => {
      const runtimeSource =
        (await loadRuntimeSource()) ??
        (existsSync(runtimePath) ? readFileSync(runtimePath, "utf-8") : null);
      if (!runtimeSource) return c.text("runtime not available", 404);
      return c.body(runtimeSource, 200, {
        "Content-Type": "text/javascript",
        "Cache-Control": "no-store",
      });
    };
    return serve();
  });

  app.get("/api/events", (c) => {
    return streamSSE(c, async (stream) => {
      const listener = () => {
        stream.writeSSE({ event: "file-change", data: "{}" }).catch(() => {});
      };
      watcher.addListener(listener);
      while (true) {
        await stream.sleep(30000);
      }
    });
  });

  // Mount the shared studio API at /api.
  // Use fetch() forwarding (not .route()) so the sub-app sees paths without
  // the /api prefix — the shared module's path extraction uses c.req.path.
  const api = createStudioApi(adapter);
  app.all("/api/*", async (c) => {
    const url = new URL(c.req.url);
    url.pathname = url.pathname.slice(4); // Strip "/api" prefix
    const forwardReq = new Request(url.toString(), {
      method: c.req.method,
      headers: c.req.raw.headers,
      body: c.req.raw.body,
      // @ts-expect-error -- Node needs duplex for streaming bodies
      duplex: "half",
    });
    return api.fetch(forwardReq);
  });

  // Studio SPA static files
  const serveStudioStaticFile = (c: Context) => {
    const filePath = resolve(studioDir, c.req.path.slice(1));
    if (!existsSync(filePath) || !statSync(filePath).isFile()) return c.text("not found", 404);
    const content = readFileSync(filePath);
    return new Response(content, {
      headers: { "Content-Type": getMimeType(filePath), "Cache-Control": "no-store" },
    });
  };
  app.get("/assets/*", serveStudioStaticFile);
  app.get("/icons/*", serveStudioStaticFile);

  // SPA fallback
  app.get("*", (c) => {
    const indexPath = resolve(studioDir, "index.html");
    if (!existsSync(indexPath)) {
      return c.html(
        `<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>HyperFrames Studio unavailable</title>
    <style>
      body {
        margin: 0;
        min-height: 100vh;
        display: grid;
        place-items: center;
        background: #0d0f14;
        color: #eef2f7;
        font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
      }
      main {
        width: min(560px, calc(100vw - 48px));
        border: 1px solid rgba(255, 255, 255, 0.14);
        border-radius: 8px;
        padding: 28px;
        background: #151923;
      }
      h1 {
        margin: 0 0 12px;
        font-size: 22px;
        line-height: 1.2;
      }
      p {
        margin: 0 0 18px;
        color: #aab3c2;
        line-height: 1.5;
      }
      code {
        display: block;
        padding: 12px 14px;
        border-radius: 6px;
        background: #090b10;
        color: #8ff0c2;
        overflow-wrap: anywhere;
      }
    </style>
  </head>
  <body>
    <main>
      <h1>Studio bundle missing</h1>
      <p>The preview server started, but this CLI build does not contain the Studio assets.</p>
      <code>bun run build</code>
    </main>
  </body>
</html>`,
        500,
      );
    }
    return c.html(readFileSync(indexPath, "utf-8"));
  });

  return { app, watcher };
}