mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 07:50:13 +00:00
* fix(cli): a subfolder of an imported project keeps its received-files record Publish, cloud render and feedback now read the received-files record at the nearest folder at or above the one they stage, so staging a subfolder of an imported project still leaves out the outside files its received files reference. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli): a received file counts under any spelling of the same file on disk The received-files lookup now also matches a project file that is the same file on disk as a listed path, so a name respelled in letter case on a case-insensitive disk keeps its received status. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli): cloud render prepares only the GIFs staging kept The entry GIF prep before a cloud render upload now reads only the staged copies it is handed. An image whose source staging left out keeps its reference as written and is never read from disk. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli,studio-server): never hand a playlist named as media to ffmpeg A media file whose first bytes are an HLS playlist, an XML manifest or a concat script now stays out of ffprobe and ffmpeg: cloud render leaves it in the zip as authored, the media probe reports it as not media, and the proxy copy refuses it. Real media never starts with these bytes, so it probes and transcodes as before. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(studio-server): catch playlists with control bytes, and keep them from stills and audio probes A text playlist or concat script is detected whatever bytes follow its first line; only markup must be all text. A still frame and the audio probe behind waveforms, peaks and loudness now refuse a file the probe reads as not media, as the proxy copy already does. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli): a parent folder's state the CLI cannot read never marks a project received The walk up for a received-files record now skips a parent whose record cannot be reached. Only a record file that is there but cannot be read or parsed counts every file as received. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli): a drive that reports no file ids matches no received file by identity Some network and virtual drives report a file id of 0 for every file, so the same-file match now gives such a file no identity instead of matching it to every listed file. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(studio-server): read a media file's first bytes with a read stream The playlist check reads the first 64 bytes through a bounded read stream instead of a raw file descriptor, and the audio-track probe's doc comment sits on its function again. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * chore(studio-server): raise the packed size budget for the media playlist check Main packs @hyperframes/studio-server close to the 1% tolerance on the 168500 budget, and the playlist check adds about 320 bytes, which put the Build over. Set the budget to 172000. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli,studio-server): open media only through self-contained media demuxers Every ffprobe and ffmpeg input that cloud render offload, the publish proxy bake and Studio's media helpers open now carries a demuxer whitelist built from the supported media extensions: MP4/MOV/M4A/AVIF, Matroska/WebM, MXF, AVI, MPEG-PS/TS, FLV, ASF, Ogg, WAV, MP3, AAC, FLAC, AIFF and the still-image formats. Playlist, manifest and concat demuxers can no longer open, whatever a file's bytes say. The proxy's own concat step is left as it is. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli,studio-server): keep media probe argv flat, and expect the demuxer list in loudness args Two probe argv literals built from nested spreads are flat again, so "--" stays the visible second-to-last entry the argv contract checks. The normalize-audio test expects the demuxer list before the input. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli): play and present answer only local host names and allowed hosts play and present listen on every interface. Each request now passes the same Host check preview uses: localhost, loopback addresses and this machine's own addresses and names are answered, and any other host name gets a 403 naming HYPERFRAMES_PREVIEW_ALLOWED_HOSTS until it is listed there. Phones and other machines on the network still open them by LAN address or .local name. * fix(cli): a local render of a received composition leaves out files outside the project When the composition a local render opens is listed in the project's received-files record, hyperframes render (full and range) no longer brings in files outside the project. It prints one line naming the references it leaves out and why. An unreadable record counts as received. A project whose entry is the person's own, or that has no record, renders exactly as before. * fix(cli): received-render scan reads safely and treats an unreadable record as unknown The scan behind the received-composition notice skips a file it cannot read, finds url() references with a linear forward scan, and reads at most 2 MB of each file. An unreadable received-files record no longer counts as everything received for local render: the render keeps outside files and names the record it could not read. Publish and cloud upload still treat it as received. The notice now says the render stops on a sub-composition outside the project rather than leaving it out. * fix(cli): the studio render of a received composition leaves out files outside the project The Studio render route applies the same rule as hyperframes render: when the composition it renders is listed in the received-files record, the job does not bring in files outside the project, and the server log names the references it refuses. * chore(cli): name the unreadable received-files record helper without a comment * fix(cli): local render refuses outside files when any composition it plays was received The received-file rule for local render (CLI and Studio) now checks every page and stylesheet the render pulls in, not only the entry, so an own index.html that plays a received scene also reads nothing outside the project, and the notice names the received file. An unreadable, truncated or empty received-files record refuses outside files too, as publish and cloud upload do, and the notice names the record it could not read. * fix(cli): decide a received render from the files the compiler reads Local render (CLI and Studio) now leaves outside-file handling as it is for a project with no received-files record or an empty one, without scanning anything. When the record lists files, the compiler's own read list for the composition decides: the bundler runs out of process with a deadline and reports every project file it reads, so stylesheet imports and files past any scan limit count. A received file in that list, a build that fails or runs past its deadline, or an unreadable record refuses outside files. The scan that names refused references in the notice is advisory only: it guards every file system call, tracks visited files by real path, and caps the files and bytes it reads. * fix(cli,producer): decide a received render with the render compiler's own composition traversal The producer exports renderCompositionFiles, which walks data-composition-src with the same resolution, normalization and private file rules the render's sub-composition pass uses; that pass now calls the same helper. The received-render decision adds those files to the bundler's read list, so leading-slash and percent-encoded references the render reads count. The advisory scan resolves compositions the same way and reads template contents. * fix(cli): refuse outside files in a local render whenever the project has received files A local render (CLI and Studio) reads nothing outside the project when the project's received-files record lists any file, or cannot be read. No static list matches what a render consumes: the page loads its stylesheets and scripts through the browser at capture time, and scripts can load more, so the decision no longer depends on one. The reference scan stays only to name what the notice says is left out. This drops the out-of-process bundler read list and the producer composition walk added for that decision. * fix(cli): refuse outside files only when a received file can load other files A local render (CLI and Studio) reads nothing outside the project when the received-files record cannot be read, or lists a received file that can reference others: an .html, .htm, .css, .js, .mjs, .cjs or .svg name, or content that reads as HTML, SVG or CSS. A project that only received images, video, audio or fonts keeps bringing in outside files as before. * fix(cli): keep outside files only when every received file is positively media, a font or an image A local render keeps bringing in outside files only when each file the received-files record lists has a known media, font or image extension and starts with that type's signature bytes. Any other received file, a listed file that is missing or unreadable, or a mismatch between name and content refuses outside files. An ancestor record's entries now match a subfolder whose name is spelled in another Unicode form; the entry keeps its own spelling on disk. * fix(producer,core): a sub-composition must be an .html file The render compiler and the runtime load a data-composition-src only when it names an .html or .htm file. Any other file, such as an image or video, is refused as a page: render stops naming it, and the runtime reports the load failure without fetching it. * fix(producer,cli): the render and static file servers forbid type sniffing Both servers send X-Content-Type-Options: nosniff with every response, so the browser loads a file only as the type its extension names: an image or video cannot run as a script or apply as a stylesheet. .cjs is served as JavaScript. * test(cli): a received media file in a composition slot is refused as a page * test(cli): an empty nested received-files record cannot hide an outer record's received page * fix(cli): a received media file reached under another name refuses outside files The received-render decision now compares file identities, not names. It walks the project once, bounded by entry count and time, and refuses outside files when a hardlink or a symlink with a name that is not media reaches a received file, or when the walk cannot finish. A received file with no identity matches nothing, as in the received files check. * fix(cli): compare received files by link target and keep outside files for an empty record A received media file and every other project name are now compared by the identity of the file they reach with links followed. A linked folder that leads outside the project, or a file whose identity cannot be read, counts as unchecked and refuses outside files. An empty received-files record keeps outside files without walking the project. * chore: raise the producer unpacked size budget for the composition file checks --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
1289 lines
52 KiB
TypeScript
1289 lines
52 KiB
TypeScript
/**
|
|
* 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 { realpath } from "@hyperframes/core";
|
|
import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync, unlinkSync } from "node:fs";
|
|
import { replaceFileAtomically } from "@hyperframes/core/atomic-file";
|
|
import { createHash } from "node:crypto";
|
|
import { fileURLToPath } from "node:url";
|
|
import { resolve, join, basename, relative, sep } from "node:path";
|
|
import { readBundleFile } from "./readBundleFile.js";
|
|
import { GSAP_CDN_VERSION } from "@hyperframes/core/gsap-cdn";
|
|
import { GSAP_VENDOR_FILES, resolveGsapVendorDir } from "./gsapVendor.js";
|
|
import {
|
|
createProjectWatcher,
|
|
shouldWatchProjectFile,
|
|
type ProjectWatcher,
|
|
} from "./fileWatcher.js";
|
|
import {
|
|
hashSignatureParts,
|
|
loadRuntimeSource,
|
|
loadRuntimeSourceSignature,
|
|
} from "./runtimeSource.js";
|
|
import { VERSION as version } from "../version.js";
|
|
import {
|
|
buildStudioHeadScriptsForHost,
|
|
identityAllowed,
|
|
refreshTelemetryPosture,
|
|
resolveCliTelemetryDistinctId,
|
|
} from "./telemetryIdentity.js";
|
|
import { emitStudioRenderComplete, emitStudioRenderError } from "./studioRenderTelemetry.js";
|
|
import { startRenderCpuSampler } from "../telemetry/renderCpu.js";
|
|
import { mountDesktopRoutes } from "./desktopRoutes.js";
|
|
import {
|
|
hostHeaderAllowed,
|
|
PREVIEW_ALLOWED_HOSTS_ENV,
|
|
previewAllowedHostsFromEnv,
|
|
} from "@hyperframes/studio-server/request-identity";
|
|
import { mountShareRoutes } from "./shareRoutes.js";
|
|
import { isDevMode } from "../utils/env.js";
|
|
import { outsideAssetsAllowed } from "../utils/receivedRender.js";
|
|
import { insideHostApp } from "../utils/desktopApp.js";
|
|
import { runRenderSetupWorker } from "../utils/cancellableProcess.js";
|
|
import { acquireRenderLock, describeRenderLockHolder } from "../utils/renderLock.js";
|
|
import type { ProjectLintResult } from "@hyperframes/lint";
|
|
import { resolveRenderBrowser } from "../browser/preflight.js";
|
|
import {
|
|
createStudioManualEditsRenderBodyScript,
|
|
createStudioApi,
|
|
createProjectSignature,
|
|
createBackgroundRemovalJob,
|
|
identifyFileWrite,
|
|
DELETED_VERSION,
|
|
fileContentVersion,
|
|
getMimeType,
|
|
affectsProjectSignature,
|
|
compositionsAffectedBy,
|
|
affectsPreview,
|
|
type PreviewApiAdapter,
|
|
PREVIEW_BUNDLE_OPTIONS,
|
|
createPreviewDocumentStore,
|
|
thumbnailDeviceScaleFactor,
|
|
grantCaptureLoads,
|
|
type ResolvedProject,
|
|
type RenderJobState,
|
|
type BackgroundRemovalRender,
|
|
DEFAULT_HISTORY_ROOT,
|
|
openProjectHistory,
|
|
HistoryBusyError,
|
|
HistoryClosedError,
|
|
historyCache,
|
|
} from "@hyperframes/studio-server";
|
|
import { encoderJobOptions } from "@hyperframes/studio-server/encoder-options";
|
|
import { isLinkFreeWithinProject } from "@hyperframes/studio-server/safe-path";
|
|
import { resolveAutoProxy } from "../utils/projectConfig.js";
|
|
import {
|
|
clearElementScreenshotIsolation,
|
|
getElementScreenshotClip,
|
|
} from "@hyperframes/studio-server/screenshot-clip";
|
|
import type { ScreenshotClip } from "@hyperframes/studio-server/screenshot-clip";
|
|
import type { RenderJob } from "@hyperframes/producer";
|
|
import { isWithinProjectRoot } from "@hyperframes/parsers/asset-resolution";
|
|
import { seekCompositionTimeline } from "../capture/captureCompositionFrame.js";
|
|
import { createThumbnailPages } from "./thumbnailPages.js";
|
|
import {
|
|
assertWebGpuAdapterAvailable,
|
|
compositionRequiresWebGpu,
|
|
resolveCaptureBrowserGpuMode,
|
|
resolveLocalBrowserGpuMode,
|
|
resolveLocalWebGpu,
|
|
type BrowserGpuMode,
|
|
type ResolvedBrowserGpuMode,
|
|
} from "../browser/gpuPolicy.js";
|
|
import { loadSharpInBackground } from "../utils/optionalPackages.js";
|
|
|
|
export { originForListeningAddress } from "@hyperframes/studio-server";
|
|
|
|
const STUDIO_MANUAL_EDITS_PATH = ".hyperframes/studio-manual-edits.json";
|
|
|
|
// Under preview.ts's 3s process-exit watchdog, so shutdown() always returns
|
|
// before that watchdog can fire and skip this file's browser cleanup.
|
|
const RENDER_SHUTDOWN_WAIT_MS = 2_000;
|
|
|
|
// Vite emits only content-hashed files under dist/assets; hand-authored
|
|
// public/ files land at the dist root. The route is the signal because the
|
|
// filename is not: rollup's base64url hash may itself contain a hyphen.
|
|
const IMMUTABLE_CACHE_CONTROL = "public, max-age=31536000, immutable";
|
|
|
|
const REMOTE_GIF_IMG_SRC_RE =
|
|
/<img\b[^>]*?\bsrc\s*=\s*["'](https?:\/\/[^"']+\.gif(?:[?#][^"']*)?)["'][^>]*>/gi;
|
|
|
|
async function loadStudioProducer() {
|
|
if (!isDevMode()) return await import("@hyperframes/producer");
|
|
// The producer's SOURCE uses the TS convention of `.js` specifiers naming
|
|
// `.ts` files, which bun resolves and Node does not. Node 22 strips TS types
|
|
// natively, so a Node-hosted dev server boots fine and only dies here, as
|
|
// `Cannot find module .../renderOrchestrator.js` with no other context.
|
|
// Vite's own shebang is `#!/usr/bin/env node` and it hosts this API
|
|
// in-process, so `vite` without `bun --bun` lands exactly here.
|
|
if (!process.versions.bun) {
|
|
throw new Error(
|
|
"Studio dev-mode rendering requires bun (the producer is loaded from TypeScript source, " +
|
|
"which Node cannot resolve). Restart the studio with `bun run studio`.",
|
|
);
|
|
}
|
|
return await import("../../../producer/src/index.js");
|
|
}
|
|
|
|
// ── 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;
|
|
}
|
|
|
|
// Same-origin root for the GSAP files the CLI ships (build-copy.mjs), laid out
|
|
// like an npm mirror so preview can ask for `<root>/gsap@<version>/dist/<file>`.
|
|
const GSAP_LOCAL_ROOT = "/api/vendor/npm";
|
|
function readStudioManualEditManifestContent(projectDir: string): string {
|
|
const manifestPath = join(projectDir, STUDIO_MANUAL_EDITS_PATH);
|
|
if (!existsSync(manifestPath)) return "";
|
|
try {
|
|
return readFileSync(manifestPath, "utf-8");
|
|
} catch {
|
|
return "";
|
|
}
|
|
}
|
|
|
|
async function applyStudioManualEditsToThumbnailPage(
|
|
page: import("puppeteer-core").Page,
|
|
manifestContent: string,
|
|
activeCompositionPath: string,
|
|
): Promise<void> {
|
|
const script = createStudioManualEditsRenderBodyScript(manifestContent, {
|
|
activeCompositionPath,
|
|
});
|
|
if (!script) return;
|
|
await page.addScriptTag({ content: script });
|
|
}
|
|
|
|
async function reapplyStudioManualEditsToThumbnailPage(
|
|
page: import("puppeteer-core").Page,
|
|
): Promise<void> {
|
|
await page.evaluate(() => {
|
|
const apply = (window as Window & { __hfStudioManualEditsApply?: () => number })
|
|
.__hfStudioManualEditsApply;
|
|
if (typeof apply === "function") apply();
|
|
});
|
|
}
|
|
|
|
function collectRemoteGifImageSources(html: string): string[] {
|
|
const urls = new Set<string>();
|
|
const re = new RegExp(REMOTE_GIF_IMG_SRC_RE.source, REMOTE_GIF_IMG_SRC_RE.flags);
|
|
let match: RegExpExecArray | null;
|
|
while ((match = re.exec(html)) !== null) {
|
|
if (match[1]) urls.add(match[1]);
|
|
}
|
|
return [...urls];
|
|
}
|
|
|
|
async function downloadRemoteGifImageSources(
|
|
html: string,
|
|
downloadDir: string,
|
|
downloadToTemp: (url: string, destDir: string) => Promise<string>,
|
|
): Promise<Map<string, string>> {
|
|
const sourceAssets = new Map<string, string>();
|
|
await Promise.all(
|
|
collectRemoteGifImageSources(html).map(async (url) => {
|
|
try {
|
|
sourceAssets.set(url, await downloadToTemp(url, downloadDir));
|
|
} catch (err) {
|
|
console.warn(
|
|
"[Studio] Remote animated GIF prep skipped:",
|
|
err instanceof Error ? err.message : err,
|
|
);
|
|
}
|
|
}),
|
|
);
|
|
return sourceAssets;
|
|
}
|
|
|
|
// ── Shared thumbnail browser (pool-backed) ──────────────────────────────────
|
|
// Uses the engine's browser pool so the thumbnail browser and render workers
|
|
// share a single Chrome process instead of running two independent ones.
|
|
|
|
let _thumbnailBrowserLease: import("@hyperframes/engine").BrowserLease | null = null;
|
|
const thumbnailPages = createThumbnailPages();
|
|
let _thumbnailBrowserInitializing: Promise<ThumbnailBrowserSession | null> | null = null;
|
|
let _thumbnailBrowserModes: {
|
|
requested: BrowserGpuMode;
|
|
resolved: ResolvedBrowserGpuMode;
|
|
softwareWebGpu: boolean;
|
|
} | null = null;
|
|
|
|
interface ThumbnailBrowserSession {
|
|
browser: import("puppeteer-core").Browser;
|
|
requestedGpuMode: BrowserGpuMode;
|
|
resolvedGpuMode: ResolvedBrowserGpuMode;
|
|
softwareWebGpu: boolean;
|
|
}
|
|
|
|
async function getThumbnailBrowser(
|
|
requestedGpuMode: BrowserGpuMode,
|
|
isShuttingDown: () => boolean,
|
|
): Promise<ThumbnailBrowserSession | null> {
|
|
if (isShuttingDown()) return null;
|
|
if (
|
|
_thumbnailBrowserLease?.browser.connected &&
|
|
_thumbnailBrowserModes?.requested === requestedGpuMode
|
|
) {
|
|
return {
|
|
browser: _thumbnailBrowserLease.browser,
|
|
requestedGpuMode: _thumbnailBrowserModes.requested,
|
|
resolvedGpuMode: _thumbnailBrowserModes.resolved,
|
|
softwareWebGpu: _thumbnailBrowserModes.softwareWebGpu,
|
|
};
|
|
}
|
|
if (_thumbnailBrowserInitializing) {
|
|
const session = await _thumbnailBrowserInitializing;
|
|
if (session?.requestedGpuMode === requestedGpuMode) return session;
|
|
}
|
|
if (_thumbnailBrowserLease) await closeThumbnailBrowser();
|
|
|
|
_thumbnailBrowserInitializing = (async () => {
|
|
try {
|
|
if (isShuttingDown()) return null;
|
|
const { ensureBrowser } = await import("../browser/manager.js");
|
|
const { acquireBrowser, buildChromeArgs } = await import("@hyperframes/engine");
|
|
let executablePath: string | undefined;
|
|
|
|
try {
|
|
const b = await ensureBrowser({ preferManagedChrome: true });
|
|
executablePath = b.executablePath;
|
|
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 resolvedGpuMode = await resolveCaptureBrowserGpuMode(requestedGpuMode, executablePath);
|
|
const { gpuConfig, softwareWebGpu } = resolveLocalWebGpu(resolvedGpuMode, true);
|
|
const acquired = await acquireBrowser(
|
|
buildChromeArgs(
|
|
{
|
|
width: 1920,
|
|
height: 1080,
|
|
captureMode: "screenshot",
|
|
requiresWebGpu: softwareWebGpu,
|
|
},
|
|
gpuConfig,
|
|
),
|
|
{ forceScreenshot: true },
|
|
);
|
|
_thumbnailBrowserLease = acquired;
|
|
_thumbnailBrowserModes = {
|
|
requested: requestedGpuMode,
|
|
resolved: resolvedGpuMode,
|
|
softwareWebGpu,
|
|
};
|
|
acquired.browser.on("disconnected", () => {
|
|
if (_thumbnailBrowserLease !== acquired) return;
|
|
_thumbnailBrowserLease = null;
|
|
_thumbnailBrowserModes = null;
|
|
_thumbnailBrowserInitializing = null;
|
|
});
|
|
return { browser: acquired.browser, requestedGpuMode, resolvedGpuMode, softwareWebGpu };
|
|
} catch (err) {
|
|
console.warn(
|
|
"[Studio] Failed to launch thumbnail browser:",
|
|
err instanceof Error ? err.message : err,
|
|
);
|
|
_thumbnailBrowserInitializing = null;
|
|
return null;
|
|
}
|
|
})();
|
|
|
|
return _thumbnailBrowserInitializing;
|
|
}
|
|
|
|
async function closeThumbnailBrowser(): Promise<void> {
|
|
thumbnailPages.closeAll();
|
|
// A launch kicked off just before this call isn't in _thumbnailBrowserLease
|
|
// yet; awaiting it here closes a browser that was mid-launch when the stop
|
|
// signal arrived, instead of leaving it running, unreferenced, after exit.
|
|
if (_thumbnailBrowserInitializing) await _thumbnailBrowserInitializing.catch(() => {});
|
|
if (!_thumbnailBrowserLease) return;
|
|
const lease = _thumbnailBrowserLease;
|
|
_thumbnailBrowserLease = null;
|
|
_thumbnailBrowserModes = null;
|
|
_thumbnailBrowserInitializing = null;
|
|
await lease.release().catch(() => {});
|
|
}
|
|
|
|
// ── Server factory ──────────────────────────────────────────────────────────
|
|
|
|
export interface StudioServerOptions {
|
|
projectDir: string;
|
|
/** Display name for the project. Defaults to basename of projectDir. */
|
|
projectName?: string;
|
|
/**
|
|
* Auto-transcode browser-hostile video codecs to a cached H.264 preview
|
|
* proxy. The preview command passes its resolved `--proxy`/`--no-proxy` +
|
|
* `hyperframes.json` value; when omitted, the project's `media.autoProxy`
|
|
* config (default true) applies.
|
|
*/
|
|
autoProxy?: boolean | undefined;
|
|
/** GPU policy used by Studio thumbnails and frame capture. */
|
|
browserGpuMode?: BrowserGpuMode;
|
|
/** Where project histories are kept; defaults to ~/.cache/hyperframes/history. */
|
|
historyRoot?: string;
|
|
origin?: () => string | undefined;
|
|
}
|
|
|
|
export interface StudioServer {
|
|
app: Hono;
|
|
watcher: ProjectWatcher;
|
|
/** Cancels in-flight renders, then closes every browser this server owns. */
|
|
shutdown(): Promise<void>;
|
|
/** Exposed for tests: the adapter handed to the shared studio API (carries
|
|
* the resolved `autoProxy` flag the preview routes read). */
|
|
adapter: PreviewApiAdapter;
|
|
}
|
|
|
|
export async function loadPreviewServerBuildSignature(): Promise<string> {
|
|
const runtimeSignature = await loadRuntimeSourceSignature();
|
|
const studioBundle = resolveStudioBundle();
|
|
const studioIndex = studioBundle.available
|
|
? (readBundleFile(studioBundle.indexPath)?.toString("utf-8") ?? "")
|
|
: "";
|
|
return hashSignatureParts([
|
|
version,
|
|
runtimeSignature,
|
|
studioIndex,
|
|
createStudioServer.toString(),
|
|
createStudioApi.toString(),
|
|
createProjectSignature.toString(),
|
|
getMimeType.toString(),
|
|
getElementScreenshotClip.toString(),
|
|
]);
|
|
}
|
|
|
|
// Rewrite the viewport meta + inline width/height in every written .html to the
|
|
// host composition's dimensions, so an installed fragment matches the host
|
|
// canvas. Applies to ALL written files — including any .html a dependency ships,
|
|
// not just the requested block's — which is intentional. No-op when the host
|
|
// index.html is absent or carries no dimensions.
|
|
function rewriteWrittenToHostViewport(projectDir: string, written: string[]): void {
|
|
const indexPath = join(projectDir, "index.html");
|
|
if (!existsSync(indexPath)) return;
|
|
const indexHtml = readFileSync(indexPath, "utf-8");
|
|
const hostW = indexHtml.match(/data-width="(\d+)"/)?.[1];
|
|
const hostH = indexHtml.match(/data-height="(\d+)"/)?.[1];
|
|
if (!hostW || !hostH) return;
|
|
|
|
for (const absPath of written) {
|
|
if (!absPath.endsWith(".html")) continue;
|
|
let content = readFileSync(absPath, "utf-8");
|
|
content = content.replace(
|
|
/(<meta\s+name="viewport"\s+content="width=)\d+(,\s*height=)\d+/i,
|
|
`$1${hostW}$2${hostH}`,
|
|
);
|
|
content = content.replace(
|
|
/(\bwidth:\s*)\d+(px;\s*\n?\s*height:\s*)\d+(px;)/g,
|
|
(match, pre, mid, post) => {
|
|
if (match.includes("1920") || match.includes("1080")) {
|
|
return `${pre}${hostW}${mid}${hostH}${post}`;
|
|
}
|
|
return match;
|
|
},
|
|
);
|
|
replaceFileAtomically(absPath, content, statSync(absPath).mode);
|
|
}
|
|
}
|
|
|
|
function createStateFolderBeforeWatching(projectDir: string): void {
|
|
try {
|
|
mkdirSync(join(projectDir, ".hyperframes"), { recursive: true });
|
|
} catch {
|
|
return;
|
|
}
|
|
}
|
|
|
|
export function createStudioServer(options: StudioServerOptions): StudioServer {
|
|
const { projectDir, projectName } = options;
|
|
const projectId = projectName || basename(projectDir);
|
|
const browserGpuMode = options.browserGpuMode ?? resolveLocalBrowserGpuMode();
|
|
const studioDir = resolveDistDir();
|
|
const runtimePath = resolveRuntimePath();
|
|
const gsapVendorDir = resolveGsapVendorDir();
|
|
createStateFolderBeforeWatching(projectDir);
|
|
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((changedPath) => {
|
|
if (changedPath === "." || affectsProjectSignature(projectDir, join(projectDir, changedPath))) {
|
|
cachedProjectSignature = null;
|
|
}
|
|
});
|
|
const projectSignature = (dir: string): string => {
|
|
if (resolve(dir) !== resolve(projectDir)) return createProjectSignature(dir);
|
|
cachedProjectSignature ??= createProjectSignature(projectDir);
|
|
return cachedProjectSignature;
|
|
};
|
|
|
|
// Opened on first use, so a server that never serves Studio's history never writes one. A failed open stays off
|
|
// for this run; one another process was holding is tried again on the next request, which no write waits for.
|
|
let ownerWaitMs: number | undefined;
|
|
const historyUrl = () => {
|
|
const origin = options.origin?.();
|
|
return origin && `${origin}/api/projects/${encodeURIComponent(projectId)}/history`;
|
|
};
|
|
const histories = historyCache(() =>
|
|
openProjectHistory({
|
|
projectDir,
|
|
historyRoot: options.historyRoot ?? DEFAULT_HISTORY_ROOT,
|
|
ownerWaitMs,
|
|
ownerUrl: historyUrl(),
|
|
})
|
|
.then((history) => {
|
|
ownerWaitMs = undefined;
|
|
return history;
|
|
})
|
|
.catch((error: unknown) => {
|
|
console.warn(`[studio] Project history is off: ${String(error)}`);
|
|
if (error instanceof HistoryBusyError) ownerWaitMs = 0;
|
|
if (error instanceof HistoryBusyError || error instanceof HistoryClosedError)
|
|
histories.forget(projectDir);
|
|
return null;
|
|
}),
|
|
);
|
|
const projectHistory = () => histories.get(projectDir);
|
|
const hostAppOwnsHistory = insideHostApp();
|
|
watcher.addListener((changedPath) => {
|
|
void histories.peek(projectDir)?.then((opened) => opened?.noteChange(changedPath));
|
|
});
|
|
|
|
const inFlightRenders = new Map<AbortController, Promise<void>>();
|
|
// Set synchronously by shutdown() before any await, so a render or
|
|
// thumbnail request already queued behind it sees the flag instead of
|
|
// launching a browser shutdown() has no way to know about and close.
|
|
let shuttingDown = false;
|
|
|
|
const adapter: PreviewApiAdapter = {
|
|
history: () => (hostAppOwnsHistory ? null : projectHistory()),
|
|
loadSharp: () => loadSharpInBackground("image thumbnails"),
|
|
// Explicit option wins (preview's resolved --proxy/--no-proxy + config);
|
|
// otherwise honor the project's hyperframes.json media.autoProxy so every
|
|
// createStudioServer caller (e.g. the background preview child) gets the
|
|
// configured behavior without its own plumbing.
|
|
autoProxy: options.autoProxy ?? resolveAutoProxy(projectDir, undefined),
|
|
|
|
listProjects: () => [project],
|
|
|
|
// Salted with the running CLI file, so an upgraded CLI never serves an older build's document.
|
|
previewDocuments: createPreviewDocumentStore(
|
|
projectDir,
|
|
createHash("sha256")
|
|
.update(readFileSync(fileURLToPath(import.meta.url)))
|
|
.digest("hex"),
|
|
),
|
|
|
|
resolveProject: (id: string) => (id === projectId ? project : null),
|
|
|
|
async bundle(dir, options): 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, { ...PREVIEW_BUNDLE_OPTIONS, ...options });
|
|
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;
|
|
}
|
|
},
|
|
|
|
async transformPreviewHtml({ html, project }) {
|
|
const { injectDeterministicFontFaces } = await import("@hyperframes/core/fonts/embed");
|
|
const { prepareAnimatedGifInputs } =
|
|
await import("../../../producer/src/services/animatedGifPrep.js");
|
|
const { prepareHeifImageInputs } =
|
|
await import("../../../producer/src/services/heifImagePrep.js");
|
|
const { downloadToTemp, writeUrlDownloadTelemetry } =
|
|
await import("../../../producer/src/utils/urlDownloader.js");
|
|
const gifOutputDir = join(project.dir, ".hyperframes", "prepared-assets", "gif");
|
|
const gifDownloadDir = join(project.dir, ".hyperframes", "prepared-assets", "downloads");
|
|
const heifOutputDir = join(project.dir, ".hyperframes", "prepared-assets", "heif");
|
|
const preparedDirs = [gifOutputDir, gifDownloadDir, heifOutputDir];
|
|
if (!preparedDirs.every((dir) => isLinkFreeWithinProject(project.dir, dir)))
|
|
return injectDeterministicFontFaces(html);
|
|
const { html: htmlWithJpegs } = await prepareHeifImageInputs(html, {
|
|
projectDir: project.dir,
|
|
downloadDir: gifDownloadDir,
|
|
outputDir: heifOutputDir,
|
|
outputSrcPrefix: ".hyperframes/prepared-assets/heif",
|
|
onFailure: (error) => console.warn(`[studio] ${error.message}`),
|
|
});
|
|
const prepared = await prepareAnimatedGifInputs(htmlWithJpegs, {
|
|
projectDir: project.dir,
|
|
downloadDir: gifDownloadDir,
|
|
outputDir: gifOutputDir,
|
|
outputSrcPrefix: ".hyperframes/prepared-assets/gif",
|
|
cacheDir: gifOutputDir,
|
|
sourceAssets: await downloadRemoteGifImageSources(html, gifDownloadDir, (url, destDir) =>
|
|
downloadToTemp(url, destDir, undefined, undefined, undefined, {
|
|
onTelemetry: writeUrlDownloadTelemetry,
|
|
}),
|
|
),
|
|
});
|
|
return injectDeterministicFontFaces(prepared.html);
|
|
},
|
|
|
|
getProjectSignature: projectSignature,
|
|
invalidateProjectSignature: (dir: string) => {
|
|
if (resolve(dir) === resolve(projectDir)) cachedProjectSignature = null;
|
|
},
|
|
|
|
async lint(html, opts) {
|
|
const { lintHyperframeHtml } = await import("@hyperframes/lint");
|
|
return await lintHyperframeHtml(html, { ...opts, host: "studio" });
|
|
},
|
|
|
|
// Out of process: linting a large composition is seconds of synchronous parsing, and on
|
|
// this event loop it stalls every other Studio request, the preview included.
|
|
lintProject: (dir: string) =>
|
|
runRenderSetupWorker<ProjectLintResult>(
|
|
"lint",
|
|
{ projectDir: dir, host: "studio", background: true },
|
|
{ maxBufferBytes: 8 * 1024 * 1024 },
|
|
),
|
|
|
|
runtimeUrl: "/api/runtime.js",
|
|
gsapLocalRoot: gsapVendorDir ? GSAP_LOCAL_ROOT : undefined,
|
|
serverOrigin: () => options.origin?.(),
|
|
|
|
rendersDir: () => join(projectDir, "renders"),
|
|
|
|
startRender(opts): RenderJobState {
|
|
if (shuttingDown) {
|
|
return {
|
|
id: opts.jobId,
|
|
status: "failed",
|
|
progress: 0,
|
|
outputPath: opts.outputPath,
|
|
error: "Studio server is shutting down",
|
|
};
|
|
}
|
|
// The render POST is a request boundary like any other. Without this an
|
|
// already-open Studio tab keeps rendering under the posture cached when
|
|
// the server booted.
|
|
refreshTelemetryPosture();
|
|
const abortController = new AbortController();
|
|
const state: RenderJobState = {
|
|
id: opts.jobId,
|
|
status: "rendering",
|
|
progress: 0,
|
|
outputPath: opts.outputPath,
|
|
cancel: () => abortController.abort(),
|
|
};
|
|
|
|
// Run render asynchronously, mutating the state object
|
|
const startTime = Date.now();
|
|
const cpu = startRenderCpuSampler(opts.telemetryOptOut !== true);
|
|
const run = (async () => {
|
|
let renderJob: RenderJob | undefined;
|
|
const removeCancelledOutput = () => {
|
|
// User-initiated cancel: not a failure. Remove any output so the
|
|
// cancelled job doesn't resurrect in the render history.
|
|
state.status = "cancelled";
|
|
for (const suffix of ["", ".meta.json"]) {
|
|
const fp = suffix
|
|
? opts.outputPath.replace(/\.(mp4|webm|mov|gif)$/, suffix)
|
|
: opts.outputPath;
|
|
try {
|
|
if (existsSync(fp)) unlinkSync(fp);
|
|
} catch {
|
|
/* ignore */
|
|
}
|
|
}
|
|
};
|
|
try {
|
|
const { createRenderJob, executeRenderJob } = await loadStudioProducer();
|
|
const browser = await resolveRenderBrowser(abortController.signal);
|
|
if (!process.env.PRODUCER_HEADLESS_SHELL_PATH) {
|
|
process.env.PRODUCER_HEADLESS_SHELL_PATH = browser.executablePath;
|
|
}
|
|
|
|
const allowOutsideProjectAssets = outsideAssetsAllowed(
|
|
opts.project.dir,
|
|
opts.composition,
|
|
(line) => console.warn(`[studio] ${line}`),
|
|
);
|
|
const manifestContent = readStudioManualEditManifestContent(opts.project.dir);
|
|
const manualEditsRenderScript = createStudioManualEditsRenderBodyScript(manifestContent);
|
|
const job = createRenderJob({
|
|
// opts.fps is already an Fps rational — see vite-config-studio
|
|
// adapter for the same convention.
|
|
fps: opts.fps,
|
|
quality: opts.quality as "draft" | "standard" | "high",
|
|
format: opts.format,
|
|
...(opts.gifLoop !== undefined ? { gifLoop: opts.gifLoop } : {}),
|
|
outputResolution: opts.outputResolution,
|
|
...(manualEditsRenderScript ? { renderBodyScripts: [manualEditsRenderScript] } : {}),
|
|
...(opts.composition ? { entryFile: opts.composition } : {}),
|
|
...(opts.variables ? { variables: opts.variables } : {}),
|
|
...encoderJobOptions(opts),
|
|
...(opts.useGpu ? { useGpu: true } : {}),
|
|
...(opts.pageMotionBlur ? { pageMotionBlur: opts.pageMotionBlur } : {}),
|
|
allowOutsideProjectAssets,
|
|
});
|
|
renderJob = job;
|
|
const onProgress = (j: { progress: number; currentStage?: string }) => {
|
|
state.progress = j.progress;
|
|
if (j.currentStage) state.stage = j.currentStage;
|
|
};
|
|
// The CLI's one-render-slot-per-account lock: a Studio render waits behind it, and Cancel ends the wait.
|
|
const releaseSlot = await acquireRenderLock({
|
|
project: opts.project.dir,
|
|
wait: true,
|
|
signal: abortController.signal,
|
|
onWait: (holder) => {
|
|
state.stage = `Waiting for another render (${describeRenderLockHolder(holder, Date.now())})`;
|
|
},
|
|
});
|
|
state.stage = undefined;
|
|
try {
|
|
await executeRenderJob(
|
|
job,
|
|
opts.project.dir,
|
|
opts.outputPath,
|
|
onProgress,
|
|
abortController.signal,
|
|
);
|
|
} finally {
|
|
releaseSlot();
|
|
}
|
|
if (abortController.signal.aborted) {
|
|
// Cancel landed just as the render finished: honor the cancel the
|
|
// route already reported instead of resurrecting a completed job.
|
|
removeCancelledOutput();
|
|
return;
|
|
}
|
|
if (job.audioLoweredDb !== undefined) state.audioLoweredDb = job.audioLoweredDb;
|
|
state.status = "complete";
|
|
state.progress = 100;
|
|
const metaPath = opts.outputPath.replace(/\.(mp4|webm|mov|gif)$/, ".meta.json");
|
|
writeFileSync(
|
|
metaPath,
|
|
JSON.stringify({
|
|
status: "complete",
|
|
durationMs: Date.now() - startTime,
|
|
...(job.audioLoweredDb !== undefined ? { audioLoweredDb: job.audioLoweredDb } : {}),
|
|
}),
|
|
);
|
|
// Refreshed HERE, not just at render start: a render can run for
|
|
// minutes, and `hyperframes telemetry disable` during one must be
|
|
// honoured by the event that reports it. Studio never polls
|
|
// /api/telemetry-identity, so this process would otherwise keep its
|
|
// startup-cached posture for the life of the preview server.
|
|
refreshTelemetryPosture();
|
|
emitStudioRenderComplete(opts, Date.now() - startTime, job.perfSummary, cpu.stop());
|
|
} catch (err) {
|
|
if (abortController.signal.aborted) {
|
|
removeCancelledOutput();
|
|
return;
|
|
}
|
|
state.status = "failed";
|
|
state.error = err instanceof Error ? err.message : String(err);
|
|
// fallow-ignore-next-line code-duplication
|
|
refreshTelemetryPosture();
|
|
emitStudioRenderError(
|
|
opts,
|
|
Date.now() - startTime,
|
|
state.stage,
|
|
err,
|
|
renderJob,
|
|
cpu.stop(),
|
|
);
|
|
try {
|
|
const metaPath = opts.outputPath.replace(/\.(mp4|webm|mov|gif)$/, ".meta.json");
|
|
writeFileSync(metaPath, JSON.stringify({ status: "failed" }));
|
|
} catch {
|
|
/* ignore */
|
|
}
|
|
} finally {
|
|
cpu.stop();
|
|
}
|
|
})();
|
|
inFlightRenders.set(abortController, run);
|
|
const forget = () => void inFlightRenders.delete(abortController);
|
|
run.then(forget, forget);
|
|
|
|
return state;
|
|
},
|
|
|
|
startBackgroundRemoval(opts) {
|
|
return createBackgroundRemovalJob(opts, async (renderOpts) => {
|
|
const sourcePipelinePath = "../background-removal/pipeline.ts";
|
|
const pipeline = (await import("../background-removal/pipeline.js").catch(
|
|
() => import(sourcePipelinePath),
|
|
)) as { render: BackgroundRemovalRender };
|
|
return pipeline.render(renderOpts);
|
|
});
|
|
},
|
|
|
|
async generateThumbnail(opts): Promise<Buffer | null> {
|
|
const session = await getThumbnailBrowser(browserGpuMode, () => shuttingDown);
|
|
if (!session) {
|
|
if (!shuttingDown) {
|
|
console.warn("[Studio] Thumbnail: no browser available — Chrome may not be installed");
|
|
}
|
|
return null;
|
|
}
|
|
const sourcePath = join(opts.project.dir, opts.compPath);
|
|
// The shared browser launches once, before any composition is known,
|
|
// so it can't gain a WebGPU flag it didn't start with. Checked live
|
|
// below, against this page, after navigation — see assertWebGpuAdapterAvailable.
|
|
const requiresWebGpu = existsSync(sourcePath)
|
|
? compositionRequiresWebGpu(readFileSync(sourcePath, "utf-8"))
|
|
: false;
|
|
if (opts.signal.aborted) return null;
|
|
const width = opts.width || 1920;
|
|
const height = opts.height || 1080;
|
|
const viewport = { width, height, deviceScaleFactor: thumbnailDeviceScaleFactor(opts) };
|
|
try {
|
|
return await thumbnailPages.withPage(
|
|
session.browser,
|
|
opts.previewUrl,
|
|
projectSignature(opts.project.dir),
|
|
opts.seekTime,
|
|
async (page) => {
|
|
await page.setViewport(viewport);
|
|
await grantCaptureLoads(await page.createCDPSession(), opts.previewUrl);
|
|
await page.goto(opts.previewUrl, { waitUntil: "domcontentloaded", timeout: 10000 });
|
|
await assertWebGpuAdapterAvailable(
|
|
page,
|
|
requiresWebGpu,
|
|
requiresWebGpu && session.softwareWebGpu,
|
|
);
|
|
await page
|
|
.waitForFunction(
|
|
() => {
|
|
const w = window as Window & {
|
|
__timelines?: Record<string, unknown>;
|
|
};
|
|
return !!(w.__timelines && Object.keys(w.__timelines).length > 0);
|
|
},
|
|
{ timeout: 5000 },
|
|
)
|
|
.catch(() => {});
|
|
},
|
|
async (page) => {
|
|
if (opts.signal.aborted) return null;
|
|
await page.setViewport(viewport);
|
|
await seekCompositionTimeline(page, opts.seekTime, {
|
|
fallbackToBridgeAndTimelines: true,
|
|
waitForPreferredSeekTargetMs: 500,
|
|
animationFrameSettle: "double",
|
|
waitForFontsMs: 500,
|
|
});
|
|
const manifestContent = readStudioManualEditManifestContent(opts.project.dir);
|
|
await applyStudioManualEditsToThumbnailPage(page, manifestContent, opts.compPath);
|
|
await page.evaluate(() => {
|
|
void document.fonts?.ready;
|
|
const body = document.body;
|
|
if (body && getComputedStyle(body).backgroundColor === "rgba(0, 0, 0, 0)") {
|
|
body.style.backgroundColor = "#1c2028";
|
|
}
|
|
});
|
|
await new Promise((r) => setTimeout(r, 200));
|
|
await reapplyStudioManualEditsToThumbnailPage(page);
|
|
if (opts.signal.aborted) return null;
|
|
try {
|
|
const clip: ScreenshotClip | undefined = opts.selector
|
|
? await page.evaluate(getElementScreenshotClip, opts.selector, opts.selectorIndex)
|
|
: undefined;
|
|
return (await page.screenshot(
|
|
opts.format === "png"
|
|
? { type: "png", ...(clip ? { clip } : {}) }
|
|
: { type: "jpeg", quality: 80, ...(clip ? { clip } : {}) },
|
|
)) as Buffer;
|
|
} finally {
|
|
if (opts.selector) await page.evaluate(clearElementScreenshotIsolation);
|
|
}
|
|
},
|
|
);
|
|
} catch (err) {
|
|
if (!opts.signal.aborted) {
|
|
console.warn(
|
|
"[Studio] Thumbnail generation failed:",
|
|
err instanceof Error ? err.message : err,
|
|
);
|
|
}
|
|
return null;
|
|
}
|
|
},
|
|
|
|
async listRegistryCatalog() {
|
|
const { listRegistryItems, loadAllItems } = await import("../registry/resolver.js");
|
|
const { loadProjectConfig } = await import("../utils/projectConfig.js");
|
|
// The same registry `add` installs from, so the panel lists what can be installed.
|
|
const registry = { baseUrl: loadProjectConfig(projectDir).registry };
|
|
const entries = await listRegistryItems(undefined, registry);
|
|
const blockAndComponentEntries = entries.filter(
|
|
(e) => e.type === "hyperframes:block" || e.type === "hyperframes:component",
|
|
);
|
|
return loadAllItems(blockAndComponentEntries, registry);
|
|
},
|
|
|
|
async installRegistryBlock(opts) {
|
|
const { addToProject, primaryInstalledTarget } = await import("../commands/add.js");
|
|
const { recordRewrittenInstall } = await import("../registry/installer.js");
|
|
const { registryTargetPath } = await import("../registry/publication.js");
|
|
const { result, item } = await addToProject({
|
|
name: opts.blockName,
|
|
projectDir: opts.project.dir,
|
|
skipClipboard: true,
|
|
source: "studio",
|
|
});
|
|
for (const warning of result.warnings) {
|
|
process.stderr.write(`hyperframes:registry ${warning}\n`);
|
|
}
|
|
const written = result.written;
|
|
|
|
rewriteWrittenToHostViewport(opts.project.dir, written);
|
|
recordRewrittenInstall(opts.project.dir, written);
|
|
|
|
// The item's own file first, as add recorded it, since Studio mounts the first .html it gets.
|
|
const root = realpath(opts.project.dir);
|
|
const primary = primaryInstalledTarget(item);
|
|
const primaryPath = registryTargetPath(root, primary);
|
|
const others = written
|
|
.filter((abs) => abs !== primaryPath)
|
|
.map((abs) => relative(root, abs).split(sep).join("/"));
|
|
return {
|
|
written: written.includes(primaryPath) ? [primary, ...others] : others,
|
|
block: item,
|
|
};
|
|
},
|
|
};
|
|
|
|
// ── Build the Hono app ─────────────────────────────────────────────────
|
|
|
|
const app = new Hono();
|
|
// Extra hosts from HYPERFRAMES_PREVIEW_ALLOWED_HOSTS (Codespaces, tunnels).
|
|
const allowedHosts = previewAllowedHostsFromEnv();
|
|
|
|
// Every route answers only loopback, the bind or an allowed host; a browser cannot forge Host.
|
|
app.use(async function refuseUnknownHost(c, next) {
|
|
const host = c.req.header("host") ?? new URL(c.req.url).host;
|
|
if (hostHeaderAllowed(host, allowedHosts)) return next();
|
|
return c.json(
|
|
{
|
|
error:
|
|
`forbidden: host "${host}" is not allowed. ` +
|
|
`Set ${PREVIEW_ALLOWED_HOSTS_ENV}=${host} to allow it ` +
|
|
`(comma separated for several hosts).`,
|
|
},
|
|
403,
|
|
);
|
|
});
|
|
|
|
// 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) => {
|
|
const serve = async () => {
|
|
const serverBuildSignature = await loadPreviewServerBuildSignature();
|
|
return c.json({
|
|
isHyperframes: true,
|
|
pid: process.pid,
|
|
projectName: projectId,
|
|
projectDir: projectDir,
|
|
serverBuildSignature,
|
|
browserGpuMode,
|
|
version,
|
|
});
|
|
};
|
|
return serve();
|
|
});
|
|
|
|
// CLI-specific routes (before shared API)
|
|
app.get("/api/runtime.js", (c) => {
|
|
const serve = async () => {
|
|
const runtimeSource =
|
|
(await loadRuntimeSource()) ?? readBundleFile(runtimePath)?.toString("utf-8") ?? null;
|
|
if (!runtimeSource) return c.text("runtime not available", 404);
|
|
return c.body(runtimeSource, 200, {
|
|
"Content-Type": getMimeType("runtime.js"),
|
|
"Cache-Control": "no-store",
|
|
});
|
|
};
|
|
return serve();
|
|
});
|
|
|
|
// Bundled GSAP for preview, so opening Studio makes no jsDelivr request.
|
|
app.get(`${GSAP_LOCAL_ROOT}/:pkg/dist/:file`, (c) => {
|
|
const file = c.req.param("file");
|
|
const body =
|
|
gsapVendorDir &&
|
|
c.req.param("pkg") === `gsap@${GSAP_CDN_VERSION}` &&
|
|
GSAP_VENDOR_FILES.has(file)
|
|
? readBundleFile(join(gsapVendorDir, file))
|
|
: null;
|
|
if (!body) return c.text("not found", 404);
|
|
return c.body(body, 200, {
|
|
"Content-Type": getMimeType(file),
|
|
"Cache-Control": "public, max-age=31536000, immutable",
|
|
});
|
|
});
|
|
|
|
// CLI → Studio telemetry identity endpoint (Layer 1). Studio reads the
|
|
// injected `window.__HF_CLI_DISTINCT_ID` first; this GET is a fallback for
|
|
// clients that can't rely on the injected global. Returns the CLI's anonymous
|
|
// distinct id (no PII) so the browser session can join the CLI's PostHog
|
|
// person, or `{ distinctId: null }` when CLI telemetry is disabled.
|
|
//
|
|
// Deliberately does NOT serve `bucketSeed`. Studio gets its canary answers
|
|
// from the injected `window.__HF_CLI_CANARY_DECISIONS` (booleans, not the
|
|
// value cohorts derive from), so nothing needs the seed over HTTP — and an
|
|
// unauthenticated local endpoint is a strictly worse place for it than an
|
|
// inline script scoped to Studio's own document.
|
|
//
|
|
// Host-guarded against DNS rebinding: a remote page can point a hostname it
|
|
// controls at 127.0.0.1 and read this response as same-origin. Pinning the
|
|
// Host header to a loopback name means such a request (which carries the
|
|
// attacker's hostname) is refused. Same-origin Studio traffic always
|
|
// presents the bound loopback host.
|
|
app.get("/api/telemetry-identity", (c) => {
|
|
if (!identityAllowed(c.req.header("host"))) {
|
|
return c.json({ error: "forbidden" }, 403);
|
|
}
|
|
// Same request-boundary refresh the head-script route does: this endpoint
|
|
// is polled by a long-lived Studio tab, so a cached posture here outlives
|
|
// an opt-out run in another terminal just as visibly.
|
|
refreshTelemetryPosture();
|
|
return c.json({ distinctId: resolveCliTelemetryDistinctId() });
|
|
});
|
|
|
|
app.get("/api/events", (c) => {
|
|
return streamSSE(c, async (stream) => {
|
|
const listener = (path: string) => {
|
|
const absPath = resolve(projectDir, path);
|
|
let version: string | null = null;
|
|
try {
|
|
version = fileContentVersion(readFileSync(absPath));
|
|
} catch {
|
|
// A deletion has no current bytes to match against an API write receipt.
|
|
}
|
|
// `version` ships even when no receipt matches: it is the client's only
|
|
// identity for an unlabelled change, and without it every duplicate
|
|
// delivery of one watcher event drains and reloads again.
|
|
const receipt = identifyFileWrite(absPath, version ?? DELETED_VERSION);
|
|
const reloads = affectsPreview(projectDir, path);
|
|
// `projectId` so a stale tab — one still pointed at a project this
|
|
// server no longer serves, because `hyperframes preview` reused this
|
|
// port for a different folder (see ProjectUnreachableBanner's doc
|
|
// comment) — can tell "my project changed" from "some OTHER project,
|
|
// now served on this same connection, changed". Every subscriber on
|
|
// this port shares one `/api/events` stream regardless of which
|
|
// project their tab was opened for; without this field a stale tab
|
|
// reloads its preview and re-reads its composition on every save the
|
|
// CURRENT project makes, 404ing each time.
|
|
stream
|
|
.writeSSE({
|
|
event: "file-change",
|
|
data: JSON.stringify({
|
|
path,
|
|
version,
|
|
projectId: project.id,
|
|
affectsPreview: reloads,
|
|
// Which thumbnails this write can change; null means all of them.
|
|
affectedCompositions: reloads ? compositionsAffectedBy(projectDir, path) : [],
|
|
...receipt,
|
|
}),
|
|
})
|
|
.catch(() => {});
|
|
};
|
|
// Re-applied here because the watcher now also emits the signature
|
|
// manifest files, which must not trigger a browser reload.
|
|
const wrappedListener = (changedPath: string) => {
|
|
if (shouldWatchProjectFile(changedPath)) listener(changedPath);
|
|
};
|
|
watcher.addListener(wrappedListener);
|
|
if (!stream.aborted) await new Promise<void>((tabClosed) => stream.onAbort(tabClosed));
|
|
watcher.removeListener(wrappedListener);
|
|
});
|
|
});
|
|
|
|
// ── Encoder availability, asked before Export is offered ────────────────
|
|
// The render route below already refuses without FFmpeg, but discovering at
|
|
// export time that the encoder was never installed is the worst possible
|
|
// moment: the user has already built the whole composition. Studio asks here
|
|
// when the Render panel opens so it can say so up front, with the same
|
|
// per-platform install command `doctor` prints.
|
|
//
|
|
// Only a passing result is cached. A user who reads the prompt, installs
|
|
// FFmpeg and hits Recheck has to get a fresh answer, or the fix they just
|
|
// applied is invisible until they restart Studio.
|
|
let ffmpegReady = false;
|
|
app.get("/api/environment/ffmpeg", async (c) => {
|
|
if (ffmpegReady) return c.json({ ok: true });
|
|
const [{ runEnvironmentChecks }, { getFFmpegInstallCommand }] = await Promise.all([
|
|
import("../browser/preflight.js"),
|
|
import("../browser/ffmpeg.js"),
|
|
]);
|
|
// With every optional check off this is exactly the FFmpeg and ffprobe
|
|
// pair — the same two `doctor` runs. ffprobe matters on its own: it ships
|
|
// with FFmpeg but is a separate binary, and a project with any media asset
|
|
// fails at probe time without it.
|
|
const { outcomes } = await runEnvironmentChecks();
|
|
const failed = outcomes.find((outcome) => !outcome.ok);
|
|
if (!failed) {
|
|
ffmpegReady = true;
|
|
return c.json({ ok: true });
|
|
}
|
|
return c.json({
|
|
ok: false,
|
|
title: failed.title ?? `${failed.name} not found`,
|
|
detail: failed.detail,
|
|
hint: failed.hint,
|
|
command: getFFmpegInstallCommand(),
|
|
});
|
|
});
|
|
|
|
mountDesktopRoutes(app, projectDir);
|
|
mountShareRoutes(app, projectDir);
|
|
|
|
// ── Pre-flight checks for render ────────────────────────────────────────
|
|
// Intercept render requests before they reach the shared API so we can
|
|
// fail fast with an actionable hint instead of burning through the entire
|
|
// capture pipeline before hitting "spawn ffmpeg ENOENT" at encode.
|
|
let cachedFFmpegPath: string | undefined;
|
|
app.post("/api/projects/:id/render", async (c, next) => {
|
|
const { findFFmpeg, getFFmpegInstallHint } = await import("../browser/ffmpeg.js");
|
|
if (!cachedFFmpegPath) {
|
|
cachedFFmpegPath = findFFmpeg();
|
|
}
|
|
if (!cachedFFmpegPath) {
|
|
return c.json({ error: "FFmpeg not found", hint: getFFmpegInstallHint() }, 503);
|
|
}
|
|
return next();
|
|
});
|
|
|
|
// 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, { allowedHosts, sandboxThumbnailCaptures: true });
|
|
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 = (cacheControl: string) => (c: Context) => {
|
|
const filePath = resolve(studioDir, c.req.path.slice(1));
|
|
// Percent escapes can decode into separators and dot segments before this
|
|
// resolve, so a hostile request can name files above the bundle
|
|
// directory. Containment stays lexical on purpose: bundle assets may sit
|
|
// behind symlinked directories (same tradeoff as the preview asset
|
|
// route), but dot segments must never collapse outside the bundle root.
|
|
if (!isWithinProjectRoot(studioDir, filePath)) return c.text("not found", 404);
|
|
const content = readBundleFile(filePath);
|
|
if (content === null) return c.text("not found", 404);
|
|
return new Response(content, {
|
|
headers: { "Content-Type": getMimeType(filePath), "Cache-Control": cacheControl },
|
|
});
|
|
};
|
|
app.get("/assets/*", serveStudioStaticFile(IMMUTABLE_CACHE_CONTROL));
|
|
app.get("/icons/*", serveStudioStaticFile("no-store"));
|
|
app.get("/favicon.svg", serveStudioStaticFile("no-store"));
|
|
|
|
// ── Runtime env injection ───────────────────────────────────────────────
|
|
// When the studio is served as a pre-built SPA, Vite `VITE_STUDIO_*` env
|
|
// vars were baked at build time. Collect any such vars from the current
|
|
// process.env and inject them as `window.__HF_STUDIO_ENV__` so the client
|
|
// can pick them up at runtime, overriding the baked defaults.
|
|
function buildRuntimeEnvScript(): string {
|
|
const overrides: Record<string, string> = {};
|
|
for (const [key, value] of Object.entries(process.env)) {
|
|
if (key.startsWith("VITE_STUDIO_") && value !== undefined) {
|
|
overrides[key] = value;
|
|
}
|
|
}
|
|
if (Object.keys(overrides).length === 0) return "";
|
|
return `<script>window.__HF_STUDIO_ENV__=${JSON.stringify(overrides)};</script>`;
|
|
}
|
|
|
|
// SPA fallback
|
|
app.get("*", (c) => {
|
|
const indexPath = resolve(studioDir, "index.html");
|
|
const indexContent = readBundleFile(indexPath);
|
|
if (indexContent === null) {
|
|
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,
|
|
);
|
|
}
|
|
let html = indexContent.toString("utf-8");
|
|
// Inject before the studio bundle runs. Identity script first (see
|
|
// buildStudioHeadScripts) so the CLI distinct id is on `window` by the time
|
|
// telemetry init reads it.
|
|
//
|
|
// Host-guarded for the same reason /api/telemetry-identity is, and it has
|
|
// to be checked HERE too: guarding only the endpoint leaves this route as
|
|
// an open side door, since a rebound origin can simply fetch `/` and read
|
|
// the same distinct id and seed out of the returned HTML.
|
|
//
|
|
// Only IDENTITY is withheld from an untrusted Host. The canary decisions
|
|
// map still goes out — it is non-identifying, and a LAN/remote Studio
|
|
// (`HYPERFRAMES_PREVIEW_HOST=0.0.0.0`) needs it to stay in agreement with
|
|
// the CLI. See buildStudioHeadScriptsForHost.
|
|
const headScript = buildStudioHeadScriptsForHost(buildRuntimeEnvScript(), c.req.header("host"));
|
|
html = html.replace(
|
|
"<head>",
|
|
`<head><meta name="hyperframes-local-share" content="1">${headScript}`,
|
|
);
|
|
// The shell names the current hashed bundle, so it always revalidates.
|
|
// `no-cache` not `no-store`: same refetch without an ETag, but `no-store`
|
|
// would blocklist the document from Chrome's bfcache.
|
|
return c.html(html, 200, { "Cache-Control": "no-cache" });
|
|
});
|
|
|
|
const shutdown = async (): Promise<void> => {
|
|
shuttingDown = true;
|
|
// Commits any open edit window; bounded with the renders below, so a history still opening cannot hold exit.
|
|
const closeHistory = histories.closeAll().catch(() => {});
|
|
const renders = [...inFlightRenders];
|
|
for (const [abortController] of renders) abortController.abort();
|
|
const { killTrackedProcesses, closeBrowserPool } = await import("@hyperframes/engine");
|
|
killTrackedProcesses();
|
|
// Browser close must not wait on renders: a render can outlast preview.ts's
|
|
// 3s watchdog, which exits without running this cleanup. closeBrowserPool
|
|
// (not drainBrowserPool) also refuses a still-unwinding render's acquire().
|
|
const closeBrowsers = Promise.allSettled([
|
|
closeThumbnailBrowser().catch(() => {}),
|
|
closeBrowserPool().catch(() => {}),
|
|
]);
|
|
await Promise.race([
|
|
Promise.allSettled([...renders.map(([, done]) => done), closeHistory]),
|
|
new Promise<void>((resolve) => setTimeout(resolve, RENDER_SHUTDOWN_WAIT_MS).unref()),
|
|
]);
|
|
await closeBrowsers;
|
|
};
|
|
|
|
return { app, watcher, adapter, shutdown };
|
|
}
|