Skip to content

Commit 67eab59

Browse files
feat(studio-server): serve H.264 proxies from the preview route (#2590)
* 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
1 parent 9d148d2 commit 67eab59

10 files changed

Lines changed: 763 additions & 43 deletions

File tree

‎.fallowrc.jsonc‎

Lines changed: 0 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -145,29 +145,6 @@
145145
"file": "packages/studio/src/utils/studioHelpers.ts",
146146
"exports": ["resolveDroppedAssetDimensions"],
147147
},
148-
// TEMP (transparent-proxy stack): proxyTranscoder is carved in below its
149-
// consumers, which land upstack (mediaProxyPreview + the preview route,
150-
// then the CLI surfaces). With no importer yet, a per-PR audit against the
151-
// merge base sees the module's whole export surface as unused. Same shape
152-
// as the drawElementService entry below. Safe to drop once the preview
153-
// weld lands; the stack's final slice greps for zero TEMP entries.
154-
{
155-
"file": "packages/studio-server/src/helpers/proxyTranscoder.ts",
156-
"exports": [
157-
"PROXY_PARAMS_VERSION",
158-
"TRANSCODE_TIMEOUT_MS",
159-
"DEFAULT_PROXY_WAIT_TIMEOUT_MS",
160-
"ProxyTranscodeError",
161-
"FfmpegMissingFilterError",
162-
"ProxyCapacityError",
163-
"ProxySourceOutsideProjectError",
164-
"ProxyWaitTimeoutError",
165-
"waitForProxy",
166-
"getProxyCachePath",
167-
"clearFailedTranscodesForTest",
168-
"resolveProxy",
169-
],
170-
},
171148
// drawElementService is the bottom of the fast-capture Graphite stack
172149
// (#1917): its consumers (frameCapture in #1919) land two PRs upstack, so
173150
// a per-PR audit diffing against the merge base sees these exports as
Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
import { describe, expect, it } from "vitest";
2+
import { maskNonScannableRanges } from "./assetResolution.js";
3+
4+
describe("maskNonScannableRanges", () => {
5+
it("masks complete comments without changing offsets", () => {
6+
const html = '<video src="before.mp4"><!-- <video src="hidden.mp4"> --><video src="after.mp4">';
7+
const masked = maskNonScannableRanges(html);
8+
9+
expect(masked).toHaveLength(html.length);
10+
expect(masked).toContain('<video src="before.mp4">');
11+
expect(masked).not.toContain("hidden.mp4");
12+
expect(masked).toContain('<video src="after.mp4">');
13+
});
14+
15+
it("handles many comment openers in linear scans", () => {
16+
const html = `prefix${"<!--".repeat(10_000)}-->suffix`;
17+
const masked = maskNonScannableRanges(html);
18+
19+
expect(masked).toHaveLength(html.length);
20+
expect(masked).toBe(`prefix${" ".repeat(html.length - 12)}suffix`);
21+
});
22+
});

‎packages/parsers/src/assetResolution.ts‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -64,10 +64,27 @@ function maskRange(src: string, pattern: RegExp): string {
6464
return src.replace(pattern, (m) => " ".repeat(m.length));
6565
}
6666

67+
function maskHtmlComments(src: string): string {
68+
const chunks: string[] = [];
69+
let cursor = 0;
70+
71+
while (true) {
72+
const start = src.indexOf("<!--", cursor);
73+
if (start === -1) break;
74+
const end = src.indexOf("-->", start + 4);
75+
if (end === -1) break;
76+
const afterComment = end + 3;
77+
chunks.push(src.slice(cursor, start), " ".repeat(afterComment - start));
78+
cursor = afterComment;
79+
}
80+
81+
return chunks.length === 0 ? src : chunks.join("") + src.slice(cursor);
82+
}
83+
6784
/** Blanks out comments, `<style>`, and `<script>` bodies so tag-scanning
6885
* regexes don't false-positive on commented-out or scripted markup. */
6986
export function maskNonScannableRanges(html: string): string {
70-
let out = maskRange(html, /<!--[\s\S]*?-->/g);
87+
let out = maskHtmlComments(html);
7188
out = maskRange(out, /<style\b[^>]*>[\s\S]*?<\/style\b[^>]*>/gi);
7289
out = maskRange(out, /<script\b[^>]*>[\s\S]*?<\/script\b[^>]*>/gi);
7390
return out;

‎packages/studio-server/package.json‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,24 @@
5656
"node": "./dist/helpers/sourceMutation.js",
5757
"import": "./src/helpers/sourceMutation.ts",
5858
"types": "./src/helpers/sourceMutation.ts"
59+
},
60+
"./media-codec-map": {
61+
"bun": "./src/helpers/mediaCodecMap.ts",
62+
"node": "./dist/helpers/mediaCodecMap.js",
63+
"import": "./src/helpers/mediaCodecMap.ts",
64+
"types": "./src/helpers/mediaCodecMap.ts"
65+
},
66+
"./proxy-transcoder": {
67+
"bun": "./src/helpers/proxyTranscoder.ts",
68+
"node": "./dist/helpers/proxyTranscoder.js",
69+
"import": "./src/helpers/proxyTranscoder.ts",
70+
"types": "./src/helpers/proxyTranscoder.ts"
71+
},
72+
"./media-proxy-preview": {
73+
"bun": "./src/helpers/mediaProxyPreview.ts",
74+
"node": "./dist/helpers/mediaProxyPreview.js",
75+
"import": "./src/helpers/mediaProxyPreview.ts",
76+
"types": "./src/helpers/mediaProxyPreview.ts"
5977
}
6078
},
6179
"publishConfig": {
@@ -89,6 +107,18 @@
89107
"./source-mutation": {
90108
"import": "./dist/helpers/sourceMutation.js",
91109
"types": "./dist/helpers/sourceMutation.d.ts"
110+
},
111+
"./media-codec-map": {
112+
"import": "./dist/helpers/mediaCodecMap.js",
113+
"types": "./dist/helpers/mediaCodecMap.d.ts"
114+
},
115+
"./proxy-transcoder": {
116+
"import": "./dist/helpers/proxyTranscoder.js",
117+
"types": "./dist/helpers/proxyTranscoder.d.ts"
118+
},
119+
"./media-proxy-preview": {
120+
"import": "./dist/helpers/mediaProxyPreview.js",
121+
"types": "./dist/helpers/mediaProxyPreview.d.ts"
92122
}
93123
},
94124
"main": "./dist/index.js",
Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
import { resolve } from "node:path";
2+
import type { StudioApiAdapter } from "../types.js";
3+
import {
4+
createMediaCodecProbeCache,
5+
scanProjectMediaCodecMap,
6+
type HtmlSourceLike,
7+
type MediaCodecMap,
8+
type MediaCodecProbeCache,
9+
} from "./mediaCodecMap.js";
10+
import { resolveProxy, PROXY_PARAMS_VERSION } from "./proxyTranscoder.js";
11+
12+
/**
13+
* Transparent-media-proxy wiring shared by `routes/preview.ts`
14+
* (docs/plans/2026-07-14-002-feat-transparent-media-proxies-plan.md, unit U3).
15+
* Split out of the route module to keep it under the repo's 600-line file cap.
16+
*/
17+
18+
/**
19+
* Preview-route-local adapter surface for the auto-proxy feature. Both
20+
* fields are optional so any existing `StudioApiAdapter` value remains
21+
* structurally assignable without editing the shared interface:
22+
* `autoProxy` defaults to true (on) when omitted — a later unit wires the
23+
* CLI `--no-proxy` flag / `hyperframes.json` setting through it;
24+
* `mediaCodecProbeCache` lets a host share one probe cache across
25+
* preview/play/static-server surfaces instead of each constructing its own.
26+
*/
27+
export type PreviewApiAdapter = StudioApiAdapter & {
28+
autoProxy?: boolean;
29+
mediaCodecProbeCache?: MediaCodecProbeCache;
30+
};
31+
32+
export function isAutoProxyEnabled(adapter: PreviewApiAdapter): boolean {
33+
return adapter.autoProxy !== false;
34+
}
35+
36+
/** One probe cache per server instance — construct once in `registerPreviewRoutes`
37+
* and reuse across every request so the mtime-cache benefit in
38+
* `scanProjectMediaCodecMap` actually applies. A host that wants to share the
39+
* cache across other surfaces (play, static project server) can pass its own
40+
* via `adapter.mediaCodecProbeCache`. */
41+
export function resolvePreviewMediaCodecProbeCache(
42+
adapter: PreviewApiAdapter,
43+
): MediaCodecProbeCache {
44+
return adapter.mediaCodecProbeCache ?? createMediaCodecProbeCache();
45+
}
46+
47+
/**
48+
* ETag salt for `?hf-proxy=` asset requests, mirroring `variablesEtagSalt` in
49+
* preview.ts: salted by the raw param value plus the transcoder's params
50+
* version, so a future proxy-recipe change (which bumps `PROXY_PARAMS_VERSION`)
51+
* or a different proxy variant invalidates cached 304s without needing to
52+
* touch the proxy file itself.
53+
*/
54+
export function proxyEtagSalt(raw: string | undefined): string {
55+
if (raw === undefined) return "";
56+
return `:proxy:${raw}:${PROXY_PARAMS_VERSION}`;
57+
}
58+
59+
// Mirrors `injectScriptTagIntoHead` in routes/preview.ts (kept local rather
60+
// than imported to avoid a helpers → routes dependency edge for one
61+
// two-line utility).
62+
function injectScriptTagIntoHead(html: string, scriptTag: string): string {
63+
if (html.includes("</head>")) return html.replace("</head>", `${scriptTag}\n</head>`);
64+
return `${scriptTag}\n${html}`;
65+
}
66+
67+
/**
68+
* Injects `window.__HF_MEDIA_CODEC_MAP__` (the U1 codec-facts scan) into
69+
* served composition HTML, and fire-and-forget pre-warms `resolveProxy` for
70+
* every browser-hostile entry so an element's proactive swap usually hits a
71+
* warm cache (KTD: protects the per-origin connection budget under held
72+
* responses). No second concurrency limiter here — the transcoder's own
73+
* global bound throttles both pre-warm and element-triggered calls.
74+
* Pre-warm failures are swallowed; an actual `?hf-proxy=` request surfaces
75+
* them as a 502. Alpha-bearing entries are never pre-warmed: the runtime
76+
* never proxies them (transparency would be destroyed).
77+
*
78+
* The single shared implementation for every auto-proxy surface — the studio
79+
* preview route (via `injectMediaCodecMap` below) and the CLI's composition /
80+
* static project servers (via the `./media-proxy-preview` subpath export).
81+
* Empty maps leave HTML untouched, preserving the normal no-hostile-media
82+
* preview path. On-demand proxy requests enforce the same eligibility gate.
83+
*/
84+
export async function injectMediaCodecMapIntoHtml(
85+
html: string,
86+
projectDir: string,
87+
htmlSources: HtmlSourceLike[],
88+
probeCache?: MediaCodecProbeCache,
89+
): Promise<string> {
90+
let map: MediaCodecMap;
91+
try {
92+
map = await scanProjectMediaCodecMap(
93+
projectDir,
94+
htmlSources,
95+
probeCache ? { cache: probeCache } : {},
96+
);
97+
} catch {
98+
// Best-effort: a scan failure must never block serving the page.
99+
return html;
100+
}
101+
if (Object.keys(map).length === 0) return html;
102+
for (const [rootRelativePathname, facts] of Object.entries(map)) {
103+
if (!facts.browserHostile || facts.hasAlpha) continue;
104+
resolveProxy(projectDir, resolve(projectDir, rootRelativePathname.replace(/^\/+/, ""))).catch(
105+
() => {
106+
// Swallowed: the pre-warm is best-effort. A real `?hf-proxy=` request
107+
// for this asset re-attempts the transcode and reports failure (502).
108+
},
109+
);
110+
}
111+
// <-escape prevents a src path containing "</script>" from breaking out of
112+
// the injected tag, mirroring injectPreviewVariables in routes/preview.ts.
113+
const json = JSON.stringify(map)
114+
.replace(/</g, "\\u003c")
115+
.replace(/\u2028/g, "\\u2028")
116+
.replace(/\u2029/g, "\\u2029");
117+
const tag = `<script data-hf-media-codec-map>window.__HF_MEDIA_CODEC_MAP__=${json};</script>`;
118+
return injectScriptTagIntoHead(html, tag);
119+
}
120+
121+
/**
122+
* Adapter-aware wrapper used by the studio preview routes: skipped entirely
123+
* (no scan, no injection) when auto-proxy is off for this adapter.
124+
*/
125+
export async function injectMediaCodecMap(
126+
html: string,
127+
adapter: PreviewApiAdapter,
128+
projectDir: string,
129+
compSrcPath: string,
130+
probeCache: MediaCodecProbeCache,
131+
): Promise<string> {
132+
if (!isAutoProxyEnabled(adapter)) return html;
133+
return injectMediaCodecMapIntoHtml(html, projectDir, [{ html, compSrcPath }], probeCache);
134+
}

‎packages/studio-server/src/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ export type {
1111
StudioSelectionTextField,
1212
} from "./types.js";
1313
export { isSafePath, walkDir } from "./helpers/safePath.js";
14+
export type { PreviewApiAdapter } from "./helpers/mediaProxyPreview.js";
1415
export { getMimeType, MIME_TYPES } from "./helpers/mime.js";
1516
export {
1617
consumeFileWriteReceipt,

‎packages/studio-server/src/routes/files.ts‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -440,7 +440,12 @@ function walkFiles(dir: string, filter: (name: string) => boolean): string[] {
440440
for (const entry of readdirSync(dir, { withFileTypes: true })) {
441441
const full = join(dir, entry.name);
442442
if (entry.isDirectory()) {
443-
if (entry.name === "node_modules" || entry.name === ".thumbnails" || entry.name === "renders")
443+
if (
444+
entry.name === "node_modules" ||
445+
entry.name === ".thumbnails" ||
446+
entry.name === "renders" ||
447+
entry.name === ".transcode-cache"
448+
)
444449
continue;
445450
results.push(...walkFiles(full, filter));
446451
} else if (filter(entry.name)) {

0 commit comments

Comments
 (0)