Skip to content

Commit 6458807

Browse files
feat(cli): let projects opt out of automatic proxying (#2591)
* feat(studio-server): serve H.264 proxies from the preview route Wires the codec manifest and the transcoder into the preview surface: the route negotiates a proxy via a query param and serves it through the existing range and ETag machinery, composition HTML carries a codec map for the runtime, and hostile assets pre-warm so a first play does not wait on a cold transcode. Exposes the three subpath exports the CLI surfaces consume upstack. Drops the TEMP fallow entry added with the transcoder: it has real importers now. * fix(studio-server): publish media proxy exports * fix(parsers): scan HTML comments linearly * feat(cli): let projects opt out of automatic proxying Adds media.autoProxy to hyperframes.json plus --proxy/--no-proxy flags, and forwards the resolved value into the studio and preview servers and the vite adapter. Lands before the runtime slice that turns auto-proxying on, so the switch exists before there is any behavior to switch off. * fix(cli): align media config schema
1 parent 67eab59 commit 6458807

10 files changed

Lines changed: 292 additions & 5 deletions

File tree

‎docs/schema/hyperframes.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,17 @@
4040
"description": "Where asset files (images, fonts, videos) land. Defaults to `assets`."
4141
}
4242
}
43+
},
44+
"media": {
45+
"type": "object",
46+
"description": "Media handling options.",
47+
"additionalProperties": false,
48+
"properties": {
49+
"autoProxy": {
50+
"type": "boolean",
51+
"description": "Automatically create H.264 proxies for browser-hostile video codecs on supported preview surfaces. Defaults to true."
52+
}
53+
}
4354
}
4455
}
4556
}

‎packages/cli/src/commands/preview.ts‎

Lines changed: 27 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,10 @@ export const examples: Example[] = [
2121
],
2222
["List all active preview servers", "hyperframes preview --list"],
2323
["Kill all active preview servers", "hyperframes preview --kill-all"],
24+
[
25+
"Disable auto-proxying of browser-hostile video codecs (HEVC, ProRes, AV1)",
26+
"hyperframes preview --no-proxy",
27+
],
2428
];
2529
import {
2630
existsSync,
@@ -56,6 +60,8 @@ import {
5660
} from "../server/portUtils.js";
5761
import { killOrphanedProcesses, killProcessTree } from "../utils/orphanCleanup.js";
5862
import { resolveProject } from "../utils/project.js";
63+
import { resolveAutoProxy } from "../utils/projectConfig.js";
64+
import { studioProxyEnv } from "../utils/studioProxyEnv.js";
5965
import {
6066
readBackgroundPreviewStatus,
6167
startBackgroundPreview,
@@ -72,10 +78,12 @@ interface BrowserLaunchOptions {
7278

7379
interface StudioLaunchOptions extends BrowserLaunchOptions {
7480
projectName?: string;
81+
autoProxy?: boolean;
7582
}
7683

7784
interface EmbeddedStudioOptions extends StudioLaunchOptions {
7885
forceNew?: boolean;
86+
autoProxy?: boolean;
7987
}
8088

8189
type StudioChildProcess = ChildProcessByStdio<null, Readable, Readable>;
@@ -181,6 +189,12 @@ export default defineCommand({
181189
description:
182190
"Launch the opened browser with --disable-gpu (requires --browser-path). For hosts where hardware acceleration crashes the graphics driver (e.g. NVIDIA Xid resets); with the system default browser use --no-open instead.",
183191
},
192+
proxy: {
193+
type: "boolean",
194+
description:
195+
"Auto-transcode browser-hostile video codecs (HEVC, ProRes, AV1) to a cached H.264 proxy for preview (default: on; overrides hyperframes.json's media.autoProxy)",
196+
negativeDescription: "Disable auto-proxying of browser-hostile video codecs",
197+
},
184198
},
185199
async run({ args }) {
186200
const startPort = parseInt(args.port ?? "3002", 10);
@@ -321,6 +335,9 @@ export default defineCommand({
321335
process.exitCode = 1;
322336
return;
323337
}
338+
// Resolve once so embedded, monorepo-dev, and locally installed Studio
339+
// modes all receive identical --proxy/--no-proxy + config semantics.
340+
const autoProxy = resolveAutoProxy(dir, args.proxy as boolean | undefined);
324341

325342
if (isDevMode()) {
326343
if (args.background) {
@@ -335,6 +352,7 @@ export default defineCommand({
335352
userDataDir,
336353
remoteDebuggingPort,
337354
browserNoGpu,
355+
autoProxy,
338356
});
339357
}
340358

@@ -352,6 +370,7 @@ export default defineCommand({
352370
userDataDir,
353371
remoteDebuggingPort,
354372
browserNoGpu,
373+
autoProxy,
355374
});
356375
}
357376

@@ -391,6 +410,7 @@ export default defineCommand({
391410
return runEmbeddedMode(dir, startPort, {
392411
projectName,
393412
forceNew,
413+
autoProxy,
394414
noOpen,
395415
browserPath,
396416
userDataDir,
@@ -924,6 +944,7 @@ async function runDevMode(dir: string, options?: StudioLaunchOptions): Promise<v
924944
const child = spawn("bun", ["run", "dev"], {
925945
cwd: studioPkgDir,
926946
stdio: ["ignore", "pipe", "pipe"],
947+
env: studioProxyEnv(options?.autoProxy ?? true),
927948
});
928949

929950
attachStudioReadyHandler(child, s, pName, dir, options);
@@ -973,6 +994,7 @@ async function runLocalStudioMode(dir: string, options?: StudioLaunchOptions): P
973994
const child = spawn(viteCommand.command, viteCommand.args, {
974995
cwd: studioPkgPath,
975996
stdio: ["ignore", "pipe", "pipe"],
997+
env: studioProxyEnv(options?.autoProxy ?? true),
976998
});
977999

9781000
attachStudioReadyHandler(child, s, pName, dir, options);
@@ -1019,7 +1041,11 @@ async function runEmbeddedMode(
10191041
return;
10201042
}
10211043

1022-
const { app } = createStudioServer({ projectDir: dir, projectName: pName });
1044+
const { app } = createStudioServer({
1045+
projectDir: dir,
1046+
projectName: pName,
1047+
autoProxy: options?.autoProxy,
1048+
});
10231049
const serverBuildSignature = await loadPreviewServerBuildSignature();
10241050

10251051
let result: FindPortResult;
Lines changed: 51 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,59 @@
1-
import { describe, expect, it } from "vitest";
1+
import { afterEach, describe, expect, it } from "vitest";
2+
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
3+
import { tmpdir } from "node:os";
4+
import { join } from "node:path";
25
import { loadHyperframeRuntimeSource } from "@hyperframes/core";
36
import { loadRuntimeSource } from "./runtimeSource.js";
7+
import { createStudioServer, type StudioServer } from "./studioServer.js";
48

59
describe("loadRuntimeSource", () => {
610
it("loads runtime source from the published core entrypoint", async () => {
711
await expect(loadRuntimeSource()).resolves.toBe(loadHyperframeRuntimeSource());
812
});
913
});
14+
15+
describe("createStudioServer autoProxy plumbing", () => {
16+
const dirs: string[] = [];
17+
let server: StudioServer | undefined;
18+
19+
function tmpProject(): string {
20+
const dir = mkdtempSync(join(tmpdir(), "hf-studio-server-test-"));
21+
dirs.push(dir);
22+
return dir;
23+
}
24+
25+
afterEach(() => {
26+
server?.watcher.close();
27+
server = undefined;
28+
for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
29+
});
30+
31+
it("hyperframes.json media.autoProxy=false flows through to the adapter", () => {
32+
const projectDir = tmpProject();
33+
writeFileSync(
34+
join(projectDir, "hyperframes.json"),
35+
JSON.stringify({ media: { autoProxy: false } }),
36+
);
37+
38+
server = createStudioServer({ projectDir });
39+
40+
expect(server.adapter.autoProxy).toBe(false);
41+
});
42+
43+
it("defaults the adapter to autoProxy=true when neither option nor config disables it", () => {
44+
server = createStudioServer({ projectDir: tmpProject() });
45+
expect(server.adapter.autoProxy).toBe(true);
46+
});
47+
48+
it("an explicit option (the preview command's resolved --proxy flag) wins over config", () => {
49+
const projectDir = tmpProject();
50+
writeFileSync(
51+
join(projectDir, "hyperframes.json"),
52+
JSON.stringify({ media: { autoProxy: false } }),
53+
);
54+
55+
server = createStudioServer({ projectDir, autoProxy: true });
56+
57+
expect(server.adapter.autoProxy).toBe(true);
58+
});
59+
});

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

Lines changed: 20 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -26,11 +26,12 @@ import {
2626
createBackgroundRemovalJob,
2727
consumeFileWriteReceipt,
2828
getMimeType,
29-
type StudioApiAdapter,
29+
type PreviewApiAdapter,
3030
type ResolvedProject,
3131
type RenderJobState,
3232
type BackgroundRemovalRender,
3333
} from "@hyperframes/studio-server";
34+
import { resolveAutoProxy } from "../utils/projectConfig.js";
3435
import { getElementScreenshotClip } from "@hyperframes/studio-server/screenshot-clip";
3536
import type { ScreenshotClip } from "@hyperframes/studio-server/screenshot-clip";
3637
import type { RenderJob } from "@hyperframes/producer";
@@ -229,11 +230,21 @@ export interface StudioServerOptions {
229230
projectDir: string;
230231
/** Display name for the project. Defaults to basename of projectDir. */
231232
projectName?: string;
233+
/**
234+
* Auto-transcode browser-hostile video codecs to a cached H.264 preview
235+
* proxy. The preview command passes its resolved `--proxy`/`--no-proxy` +
236+
* `hyperframes.json` value; when omitted, the project's `media.autoProxy`
237+
* config (default true) applies.
238+
*/
239+
autoProxy?: boolean | undefined;
232240
}
233241

234242
export interface StudioServer {
235243
app: Hono;
236244
watcher: ProjectWatcher;
245+
/** Exposed for tests: the adapter handed to the shared studio API (carries
246+
* the resolved `autoProxy` flag the preview routes read). */
247+
adapter: PreviewApiAdapter;
237248
}
238249

239250
export async function loadPreviewServerBuildSignature(): Promise<string> {
@@ -303,7 +314,13 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
303314
cachedProjectSignature = null;
304315
});
305316

306-
const adapter: StudioApiAdapter = {
317+
const adapter: PreviewApiAdapter = {
318+
// Explicit option wins (preview's resolved --proxy/--no-proxy + config);
319+
// otherwise honor the project's hyperframes.json media.autoProxy so every
320+
// createStudioServer caller (e.g. the background preview child) gets the
321+
// configured behavior without its own plumbing.
322+
autoProxy: options.autoProxy ?? resolveAutoProxy(projectDir, undefined),
323+
307324
listProjects: () => [project],
308325

309326
resolveProject: (id: string) => (id === projectId ? project : null),
@@ -785,5 +802,5 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
785802
return c.html(html);
786803
});
787804

788-
return { app, watcher };
805+
return { app, watcher, adapter };
789806
}

‎packages/cli/src/utils/projectConfig.test.ts‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ import {
88
normalizeConfig,
99
projectConfigPath,
1010
readProjectConfig,
11+
resolveAutoProxy,
1112
writeProjectConfig,
1213
PROJECT_CONFIG_FILENAME,
1314
} from "./projectConfig.js";
@@ -36,6 +37,7 @@ describe("projectConfig", () => {
3637
$schema: DEFAULT_PROJECT_CONFIG.$schema,
3738
registry: "https://example.com/my-registry",
3839
paths: { blocks: "src/blocks", components: "src/fx", assets: "media" },
40+
media: { autoProxy: true },
3941
};
4042
writeProjectConfig(dir, custom);
4143
const read = readProjectConfig(dir);
@@ -60,6 +62,28 @@ describe("projectConfig", () => {
6062
expect(result.paths.components).toBe(DEFAULT_PROJECT_CONFIG.paths.components);
6163
expect(result.paths.assets).toBe(DEFAULT_PROJECT_CONFIG.paths.assets);
6264
});
65+
66+
it("defaults media.autoProxy to true when media is absent", () => {
67+
const result = normalizeConfig({ registry: "https://alt.example.com" });
68+
expect(result.media).toEqual({ autoProxy: true });
69+
});
70+
71+
it("preserves an explicit media.autoProxy: false", () => {
72+
const result = normalizeConfig({ media: { autoProxy: false } });
73+
expect(result.media).toEqual({ autoProxy: false });
74+
});
75+
76+
it("falls back to the default when media.autoProxy is malformed", () => {
77+
const result = normalizeConfig({
78+
media: { autoProxy: "nope" } as unknown as never,
79+
});
80+
expect(result.media).toEqual({ autoProxy: true });
81+
});
82+
83+
it("falls back to the default when media itself is malformed", () => {
84+
const result = normalizeConfig({ media: "nope" as unknown as never });
85+
expect(result.media).toEqual({ autoProxy: true });
86+
});
6387
});
6488

6589
describe("readProjectConfig", () => {
@@ -123,4 +147,85 @@ describe("projectConfig", () => {
123147
}
124148
});
125149
});
150+
151+
describe("resolveAutoProxy", () => {
152+
it("defaults to true when no config file exists and no flag is passed", () => {
153+
const dir = tmp();
154+
try {
155+
expect(resolveAutoProxy(dir, undefined)).toBe(true);
156+
} finally {
157+
rmSync(dir, { recursive: true, force: true });
158+
}
159+
});
160+
161+
it("returns false when the config sets media.autoProxy: false", () => {
162+
const dir = tmp();
163+
try {
164+
writeFileSync(
165+
projectConfigPath(dir),
166+
JSON.stringify({ media: { autoProxy: false } }),
167+
"utf-8",
168+
);
169+
expect(resolveAutoProxy(dir, undefined)).toBe(false);
170+
} finally {
171+
rmSync(dir, { recursive: true, force: true });
172+
}
173+
});
174+
175+
it("defaults to true when the config file is partial and omits media", () => {
176+
const dir = tmp();
177+
try {
178+
writeFileSync(
179+
projectConfigPath(dir),
180+
JSON.stringify({ registry: "https://only-this.example.com" }),
181+
"utf-8",
182+
);
183+
expect(resolveAutoProxy(dir, undefined)).toBe(true);
184+
} finally {
185+
rmSync(dir, { recursive: true, force: true });
186+
}
187+
});
188+
189+
it("an explicit false flag wins over a config that enables it", () => {
190+
const dir = tmp();
191+
try {
192+
writeFileSync(
193+
projectConfigPath(dir),
194+
JSON.stringify({ media: { autoProxy: true } }),
195+
"utf-8",
196+
);
197+
expect(resolveAutoProxy(dir, false)).toBe(false);
198+
} finally {
199+
rmSync(dir, { recursive: true, force: true });
200+
}
201+
});
202+
203+
it("an explicit true flag wins over a config that disables it", () => {
204+
const dir = tmp();
205+
try {
206+
writeFileSync(
207+
projectConfigPath(dir),
208+
JSON.stringify({ media: { autoProxy: false } }),
209+
"utf-8",
210+
);
211+
expect(resolveAutoProxy(dir, true)).toBe(true);
212+
} finally {
213+
rmSync(dir, { recursive: true, force: true });
214+
}
215+
});
216+
217+
it("falls back to the default when the on-disk media value is malformed", () => {
218+
const dir = tmp();
219+
try {
220+
writeFileSync(
221+
projectConfigPath(dir),
222+
JSON.stringify({ media: { autoProxy: "nope" } }),
223+
"utf-8",
224+
);
225+
expect(resolveAutoProxy(dir, undefined)).toBe(true);
226+
} finally {
227+
rmSync(dir, { recursive: true, force: true });
228+
}
229+
});
230+
});
126231
});

0 commit comments

Comments
 (0)