Files
hyperframes/packages/cli/src/commands/play.ts
T
Michael Wang 2ceb682f92 fix: LAN-host previews and play pages refuse other sites without fetch metadata (#7836)
* fix(studio-server): previews with no fetch metadata on a LAN host count as another site

Browsers send no Sec-Fetch-Site header over plain HTTP to a non-loopback
name, such as a LAN address used with HYPERFRAMES_PREVIEW_HOST. The preview
guards now count such a request as the Studio's own page only when its
Referer names the same host. Otherwise the preview is marked and sandboxed,
its validators are dropped, and the thumbnail, waveform, peaks and
frame-token routes refuse it.

* fix(cli): play marks and sandboxes compositions another site loads

The play server's /composition/* route now applies the same another-site
decision as the Studio preview. A load from another site comes back with
the sandbox CSP and without validators, and its HTML carries the
hyperframes-preview-for-another-site mark, so the runtime offers that site
no editing port. The play page's own player is unchanged.

* fix(player): send a same-origin Referer from the composition frame

The player's composition iframe used no-referrer, so on a plain-HTTP LAN
host its own composition load carried neither Sec-Fetch-Site nor Referer
and the Studio and play servers sandboxed it as another site's load.
same-origin sends the host page's URL only to a composition on the same
origin, so another origin still learns nothing about the embedding page.
2026-11-15 12:34:43 +00:00

347 lines
12 KiB
TypeScript

import { failUsage, setCommandExitCode } from "../utils/commandResult.js";
import { defineCommand } from "../utils/defineCommand.js";
import type { Example } from "./_examples.js";
import { existsSync, readFileSync } from "node:fs";
export const examples: Example[] = [
["Play the current project", "hyperframes play"],
["Play a specific project directory", "hyperframes play ./my-video"],
["Use a custom port", "hyperframes play --port 8080"],
["Start without opening the browser", "hyperframes play --no-open"],
["Open with a specific browser", "hyperframes play --browser-path /usr/bin/chromium"],
[
"Open with CDP enabled (requires browser path + isolated profile)",
"hyperframes play --browser-path /usr/bin/chromium --user-data-dir /tmp/hf-profile --remote-debugging-port 9222",
],
[
"Disable auto-proxying of browser-hostile video codecs (HEVC, ProRes, AV1)",
"hyperframes play --no-proxy",
],
];
import { resolve } from "node:path";
import type { Hono } from "hono";
import { requestSubPath } from "@hyperframes/studio-server";
import * as clack from "../ui/prompts.js";
import { c } from "../ui/colors.js";
import { resolveProject, type ProjectDir } from "../utils/project.js";
import { resolveAutoProxy } from "../utils/projectConfig.js";
import { normalizeErrorMessage } from "../utils/errorMessage.js";
import { parsePort } from "../utils/port.js";
import {
openBrowser,
parseRemoteDebuggingPort,
validateRemoteDebuggingPortDeps,
} from "../utils/openBrowser.js";
import {
resolveRuntimePath,
resolvePlayerPath,
listenOnFreePort,
refuseUnknownHosts,
sandboxForAnotherSite,
injectRuntime,
injectMediaCodecMap,
buildRangeResponse,
revalidatedResponse,
assetContentType,
} from "../utils/compositionServer.js";
import { isPrivateCompositionFile } from "../utils/privateProjectFile.js";
import {
resolveProxy,
ProxyCapacityError,
ProxyTranscodeError,
} from "@hyperframes/studio-server/proxy-transcoder";
import {
decideMediaProxyEligibility,
isProxyVariantRequest,
probeAssetCodec,
recordProxyRequest,
resolveProxyVariantRequest,
PROXY_VARIANT_CONFIG,
} from "@hyperframes/studio-server/media-codec-map";
export default defineCommand({
meta: { name: "play", description: "Play a composition in a lightweight browser player" },
args: {
dir: { type: "positional", description: "Project directory", required: false },
port: { type: "string", description: "Port to run the player server on", default: "3003" },
open: {
type: "boolean",
default: true,
description: "Open browser automatically",
},
"browser-path": {
type: "string",
description: "Path to the browser executable to open",
},
"user-data-dir": {
type: "string",
description: "Chromium-compatible user data directory (requires --browser-path)",
},
"remote-debugging-port": {
type: "string",
description: "Chromium remote debugging port (requires --browser-path and --user-data-dir)",
},
proxy: {
type: "boolean",
description:
"Auto-transcode browser-hostile video codecs (HEVC, ProRes, AV1) to a cached authoring proxy for preview (default: on; overrides hyperframes.json's media.autoProxy)",
negativeDescription: "Disable auto-proxying of browser-hostile video codecs",
},
},
async run({ args }) {
let startPort: number;
try {
startPort = parsePort(args.port ?? "3003");
} catch (error) {
clack.log.error(normalizeErrorMessage(error));
failUsage();
}
const project = resolveProject(args.dir);
// Validation: --user-data-dir requires --browser-path
if (args["user-data-dir"] && !args["browser-path"]) {
clack.log.error("--user-data-dir requires --browser-path");
failUsage();
}
// Validation: --remote-debugging-port deps
const depsError = validateRemoteDebuggingPortDeps({
browserPath: args["browser-path"] as string | undefined,
userDataDir: args["user-data-dir"] as string | undefined,
remoteDebuggingPort: args["remote-debugging-port"] as string | undefined,
});
if (depsError) {
clack.log.error(depsError);
failUsage();
}
// Parse --remote-debugging-port before any server setup so an invalid value
// exits cleanly instead of leaving an orphan listening socket behind.
let remoteDebuggingPort: number | undefined;
try {
remoteDebuggingPort = parseRemoteDebuggingPort(
args["remote-debugging-port"] as string | undefined,
);
} catch (err) {
clack.log.error((err as Error).message);
failUsage();
}
// Resolve runtime path — same logic as studioServer.ts
const runtimePath = resolveRuntimePath();
if (!runtimePath) {
clack.log.error("HyperFrames runtime not found. Run `bun run build` first.");
setCommandExitCode(1);
return;
}
// Resolve player path
const playerPath = resolvePlayerPath();
if (!playerPath) {
clack.log.error(
"@hyperframes/player not found. Run `bun run --cwd packages/player build` first.",
);
setCommandExitCode(1);
return;
}
const { Hono } = await import("hono");
const { createAdaptorServer } = await import("@hono/node-server");
const app = new Hono();
refuseUnknownHosts(app);
// Serve the player JS
app.get("/player.js", (ctx) =>
revalidatedResponse(
readFileSync(playerPath, "utf-8"),
"application/javascript",
ctx.req.header("If-None-Match"),
),
);
// Serve the runtime JS
app.get("/runtime.js", (ctx) =>
revalidatedResponse(
readFileSync(runtimePath, "utf-8"),
"application/javascript",
ctx.req.header("If-None-Match"),
),
);
const autoProxy = resolveAutoProxy(project.dir, args.proxy as boolean | undefined);
await registerCompositionRoute(app, project, autoProxy);
// Main page — the player wrapper
app.get("/", (ctx) => {
return ctx.html(buildPlayerPage(project.name));
});
clack.intro(c.bold("hyperframes play"));
const s = clack.spinner();
s.start("Starting player...");
const server = createAdaptorServer({ fetch: app.fetch });
const actualPort = await listenOnFreePort(server, startPort);
const url = `http://localhost:${actualPort}`;
s.stop(c.success("Player running"));
console.log();
if (actualPort !== startPort) {
console.log(` ${c.warn(`Port ${startPort} is in use, using ${actualPort} instead`)}`);
}
console.log(` ${c.dim("Project")} ${c.accent(project.name)}`);
console.log(` ${c.dim("Player")} ${c.accent(url)}`);
console.log();
console.log(` ${c.dim("Press Ctrl+C to stop")}`);
console.log();
if (args.open) {
void openBrowser(url, {
browserPath: args["browser-path"] as string | undefined,
userDataDir: args["user-data-dir"] as string | undefined,
remoteDebuggingPort,
});
}
return new Promise<void>(() => {});
},
});
/**
* Registers the `/composition/*` route: serves composition HTML (runtime +
* `__HF_MEDIA_CODEC_MAP__` injected) and asset files, with byte-Range support
* (`play` previously did a whole-file `readFileSync`, so seeking/duration
* probing on media elements never worked) and a `?hf-proxy=` branch that
* serves the alpha-aware authoring proxy for a browser-hostile video asset
* (per docs/plans/2026-07-14-002-feat-transparent-media-proxies-plan.md,
* unit U4). Exported standalone (rather than inlined in `run()`) so tests can
* exercise it via `app.request(...)` without booting a real HTTP listener,
* `clack` UI, or `openBrowser`.
*/
export async function registerCompositionRoute(
app: Hono,
project: ProjectDir,
autoProxy: boolean,
): Promise<void> {
const { isSafePath } = await import("@hyperframes/core/studio-api");
sandboxForAnotherSite(app, "/composition/*");
// fallow-ignore-next-line complexity
app.get("/composition/*", async (ctx) => {
const reqPath = requestSubPath(ctx.req.url, "composition");
const filePath = resolve(project.dir, reqPath);
// Security: don't allow path traversal outside project dir. isSafePath
// canonicalizes symlinks and applies a trailing-separator guard, so neither
// an in-project symlink to an external target nor a sibling dir whose name
// shares the project-dir prefix (e.g. `<dir>-evil`) can escape.
if (!isSafePath(project.dir, filePath)) return ctx.text("Forbidden", 403);
if (isPrivateCompositionFile(project.dir, filePath) || !existsSync(filePath)) {
return ctx.text("Not found", 404);
}
// HTML gets the runtime + codec-map injected; other assets pass through.
if (filePath.endsWith(".html")) {
let html = injectRuntime(readFileSync(filePath, "utf-8"));
if (autoProxy) {
html = await injectMediaCodecMap(html, project.dir, [{ html, compSrcPath: reqPath }]);
}
return revalidatedResponse(html, "text/html; charset=UTF-8", ctx.req.header("If-None-Match"));
}
const contentType = assetContentType(filePath);
// Edited text is caught by a content hash; an mtime tag can repeat for a same-size rewrite.
const mediaType = contentType.split(";")[0]!.trim();
const isText =
mediaType.startsWith("text/") ||
mediaType === "application/json" ||
mediaType === "image/svg+xml";
if (isText && !ctx.req.header("Range")) {
return revalidatedResponse(
readFileSync(filePath, "utf-8"),
contentType,
ctx.req.header("If-None-Match"),
);
}
const proxyParam = ctx.req.query("hf-proxy");
if (proxyParam !== undefined && isProxyVariantRequest(proxyParam)) {
// Opt-out (or a non-video asset) 404s the param without attempting a
// transcode; a missing asset already 404'd above.
if (!autoProxy || !contentType.startsWith("video/")) return ctx.text("Not found", 404);
try {
const facts = await probeAssetCodec(filePath);
const eligibility = decideMediaProxyEligibility(facts);
if (!eligibility.eligible) {
return ctx.text(`Media proxy unavailable: ${eligibility.reason}`, 422);
}
if (!facts) return ctx.text("Media proxy unavailable: unknown_codec", 422);
const proxyVariant = resolveProxyVariantRequest(proxyParam, facts);
if (!proxyVariant) {
return ctx.text("Media proxy variant does not match asset", 422);
}
recordProxyRequest();
const proxyPath = await resolveProxy(project.dir, filePath, proxyVariant);
return buildRangeResponse(
proxyPath,
PROXY_VARIANT_CONFIG[proxyVariant].contentType,
ctx.req.header("Range"),
ctx.req.header("If-None-Match"),
);
} catch (err) {
if (err instanceof ProxyCapacityError) {
return ctx.text(`Proxy transcode deferred: ${err.message}`, 503, {
"Retry-After": "1",
});
}
if (err instanceof ProxyTranscodeError) {
return ctx.text(`Proxy transcode failed: ${err.message}`, 502);
}
throw err;
}
}
return buildRangeResponse(
filePath,
contentType,
ctx.req.header("Range"),
ctx.req.header("If-None-Match"),
);
});
}
function buildPlayerPage(projectName: string): string {
return `<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>${projectName} — HyperFrames Player</title>
<style>
* { margin: 0; padding: 0; box-sizing: border-box; }
body {
background: #0a0a0a; color: #fff;
font-family: system-ui, -apple-system, sans-serif;
height: 100vh; display: flex; flex-direction: column;
align-items: center; justify-content: center;
padding: 24px;
}
.player-wrap {
width: 100%; max-width: 1280px; aspect-ratio: 16/9;
border-radius: 8px; overflow: hidden;
}
hyperframes-player { width: 100%; height: 100%; }
.info {
margin-top: 16px; font-size: 12px; color: #444;
font-family: monospace;
}
</style>
</head>
<body>
<div class="player-wrap">
<hyperframes-player src="/composition/index.html" controls muted></hyperframes-player>
</div>
<div class="info">${projectName} — hyperframes play</div>
<script src="/player.js"></script>
</body>
</html>`;
}