Skip to content

Commit 35eff50

Browse files
feat(cli): bake proxies into published archives (#2595)
* 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 * feat(core): swap undecodable video to its proxy at runtime Adds the browser-side half: before first load the runtime consults the injected codec map and swaps a hostile source to its proxy, and if a video still reports zero decodable width it rescues it reactively. An HEVC file carrying AAC fires no error event, so zero videoWidth, not the error event, is the reliable signal. Audio elements and alpha sources are never proxied, render mode never proxies, and each swap evicts the element's stale sync state and reports once. This completes the loop: auto-proxying is live for preview and studio from here. The opt-out (media.autoProxy, --no-proxy) shipped in the previous slice. * feat(cli): serve proxies from play, present, and the static project server Adds proxy negotiation to the CLI-side servers and gives play byte-range serving it never had, so a swapped video can seek. The static project server behind check, snapshot, compare and friends injects the codec map once, so all of its callers inherit the behavior; snapshot forwards its own proxy flag. * fix(cli): serve proxies for camera formats * feat(cli): resolve proxies before check's timed browser phase check pre-resolves hostile assets so a cold transcode cannot exhaust the render-ready budget, and surfaces the runtime's proxy diagnostics as findings so a swap is visible rather than silent. * feat(cli): bake proxies into published archives Published pages are static, so there is no server to negotiate with: publish transcodes proxies for hostile assets into the archive and rewrites the video sources that point at them. Audio elements keep their originals, since audio decodes independently of the video codec. Splits the archive build from the zip step so publish can transform between them. cloud render keeps calling the unchanged composition and still uploads originals, which its regression test pins. * fix(cli): harden proxy pre-resolution * fix(cli): surface publish proxy outcomes * test(cli): remove ffmpeg from archive guard * test(cli): normalize publish fixture path
1 parent 4ad5826 commit 35eff50

5 files changed

Lines changed: 574 additions & 10 deletions

File tree

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

Lines changed: 36 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,13 @@ import type { Example } from "./_examples.js";
77
import { c } from "../ui/colors.js";
88
import { lintProject } from "../utils/lintProject.js";
99
import { formatLintFindings } from "../utils/lintFormat.js";
10-
import { publishProjectArchive } from "../utils/publishProject.js";
10+
import {
11+
buildPublishFileMap,
12+
publishProjectArchive,
13+
zipPublishFileMap,
14+
} from "../utils/publishProject.js";
15+
import { bakeMediaProxies } from "../utils/publishProxyBake.js";
16+
import { resolveAutoProxy } from "../utils/projectConfig.js";
1117
import { tryResolveCredential } from "../auth/index.js";
1218
import {
1319
ensureProjectId,
@@ -23,6 +29,7 @@ export const examples: Example[] = [
2329
["Update an existing published project in place", "hyperframes publish --update <url|id>"],
2430
["Publish to a shared team space", "hyperframes publish --space <space-id>"],
2531
["Skip the consent prompt (scripts)", "hyperframes publish --yes"],
32+
["Skip baking H.264 proxies for browser-hostile video codecs", "hyperframes publish --no-proxy"],
2633
];
2734

2835
/** Extract a project id from a published URL (with or without scheme, query, or hash) or accept a bare id. */
@@ -67,6 +74,11 @@ export default defineCommand({
6774
type: "string",
6875
description: "Publish into a shared team space (its id) so teammates update one link",
6976
},
77+
proxy: {
78+
type: "boolean",
79+
description:
80+
"Bake H.264 proxies for browser-hostile video codecs (e.g. HEVC) into the published archive. Default: on, unless disabled via hyperframes.json media.autoProxy. Pass --no-proxy to skip.",
81+
},
7082
},
7183
async run({ args }) {
7284
const rawArg = args.dir;
@@ -137,19 +149,41 @@ export default defineCommand({
137149

138150
clack.intro(c.bold("hyperframes publish"));
139151
const publishSpinner = clack.spinner();
140-
publishSpinner.start("Uploading project...");
152+
publishSpinner.start("Preparing project...");
141153

142154
try {
155+
// Resolution order (per hyperframes.json's `media.autoProxy`): an
156+
// explicit --proxy/--no-proxy flag wins in either direction, else the
157+
// committed config, else on by default.
158+
const proxyFlagValue = typeof args.proxy === "boolean" ? args.proxy : undefined;
159+
const autoProxy = resolveAutoProxy(dir, proxyFlagValue);
160+
const fileMap = buildPublishFileMap(dir);
161+
let proxyBakeManifest: Awaited<ReturnType<typeof bakeMediaProxies>> | undefined;
162+
if (autoProxy) {
163+
proxyBakeManifest = await bakeMediaProxies(dir, fileMap);
164+
}
165+
const archive = zipPublishFileMap(fileMap);
166+
publishSpinner.message("Uploading project...");
167+
143168
const published = await publishProjectArchive(dir, {
144169
public: args.public === true,
145170
projectId: requestedProjectId,
146171
spaceId,
172+
archive,
147173
});
148174
publishSpinner.stop(c.success("Project published"));
149175

150176
console.log();
151177
console.log(` ${c.dim("Project")} ${c.accent(published.title)}`);
152178
console.log(` ${c.dim("Files")} ${String(published.fileCount)}`);
179+
if (proxyBakeManifest) {
180+
console.log(` ${c.dim("Proxies")} ${String(proxyBakeManifest.proxied.length)} baked`);
181+
if (proxyBakeManifest.skippedAlpha.length > 0) {
182+
console.log(
183+
` ${c.dim("Proxy note")} ${String(proxyBakeManifest.skippedAlpha.length)} alpha source(s) kept original`,
184+
);
185+
}
186+
}
153187

154188
if (published.claimed) {
155189
// The server returns the same id on an in-place update, a fresh id on create.

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

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,11 +21,13 @@ vi.mock("./projectLink.js", () => ({
2121
}));
2222

2323
import {
24+
buildPublishFileMap,
2425
createPublishArchive,
2526
getPublishApiBaseUrl,
2627
localizeExternalAssets,
2728
publishProjectArchive,
2829
uploadTimeoutMs,
30+
zipPublishFileMap,
2931
} from "./publishProject.js";
3032

3133
function makeProjectDir(): string {
@@ -208,6 +210,41 @@ describe("createPublishArchive", () => {
208210
});
209211
});
210212

213+
describe("createPublishArchive (U6 cloud-render regression guard)", () => {
214+
// `cloud/render.ts` (`maybeUploadProject`) calls `createPublishArchive`
215+
// directly and must never see baked proxies (R2): this pins that
216+
// `createPublishArchive` is exactly the thin composition of
217+
// `buildPublishFileMap` + `zipPublishFileMap` with no baking hook, and that
218+
// a local video asset's original bytes/HTML pass through unmodified.
219+
it("keeps a source video byte-identical and excludes proxies from the cloud-render archive", () => {
220+
const dir = makeProjectDir();
221+
try {
222+
writeFileSync(
223+
join(dir, "index.html"),
224+
`<html><body><video src="clip.mp4"></video></body></html>`,
225+
"utf-8",
226+
);
227+
const originalVideo = Buffer.from("original-video-bytes");
228+
writeFileSync(join(dir, "clip.mp4"), originalVideo);
229+
230+
const direct = createPublishArchive(dir);
231+
const composed = zipPublishFileMap(buildPublishFileMap(dir));
232+
233+
expect(direct.buffer.equals(composed.buffer)).toBe(true);
234+
expect(direct.fileCount).toBe(composed.fileCount);
235+
236+
const zip = new AdmZip(direct.buffer);
237+
const entries = zip.getEntries().map((e) => e.entryName);
238+
expect(entries).toEqual(expect.arrayContaining(["index.html", "clip.mp4"]));
239+
expect(entries.some((e) => e.startsWith("_proxy/"))).toBe(false);
240+
expect(zip.readFile("clip.mp4")?.equals(originalVideo)).toBe(true);
241+
expect(zip.readAsText("index.html")).toContain('src="clip.mp4"');
242+
} finally {
243+
rmSync(dir, { recursive: true, force: true });
244+
}
245+
});
246+
});
247+
211248
describe("localizeExternalAssets", () => {
212249
it("copies external src/href assets and rewrites HTML paths", () => {
213250
const result = localizeSingleAsset("logo.png", "PNG_DATA", (rel) =>

‎packages/cli/src/utils/publishProject.ts‎

Lines changed: 67 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -254,18 +254,44 @@ function rewriteCssUrls(
254254
return { css: rewritten, modified };
255255
}
256256

257-
function rewriteHtmlAttributes(
258-
ctx: ExternalAssetContext,
257+
/** Resolves a raw attribute value (plus the referrer's absolute directory) to
258+
* the archive path it should point at, or `null` to leave it untouched. */
259+
export type HtmlAttributeResolver = (rawValue: string, referrerAbsDir: string) => string | null;
260+
261+
interface RewriteHtmlAttributesOptions {
262+
/** Attributes to inspect (default: src + href, matching the external-asset
263+
* localization use case below). */
264+
attrs?: string[];
265+
/** CSS selector narrowing which elements are inspected (default: derived
266+
* from `attrs`, e.g. `"[src], [href]"`). Callers that only care about one
267+
* tag (e.g. `<video>`) pass something like `"video[src]"`. */
268+
selector?: string;
269+
}
270+
271+
/**
272+
* Walk every element matching `selector` (default: anything with `src`/
273+
* `href`) and rewrite the given `attrs` whose value `resolveTarget` maps to an
274+
* archive path. Shared by `localizeHtmlEntry` below (external-asset
275+
* localization) and `publishProxyBake.ts` (proxy baking only rewrites
276+
* `<video src>`), so the rewrite mechanics (attribute walk + entry-relative
277+
* path rewrite) live in one place while each caller supplies its own
278+
* resolution rule.
279+
*/
280+
export function rewriteHtmlAttributes(
259281
document: Document,
260282
referrerAbsDir: string,
261283
entryPath: string,
284+
resolveTarget: HtmlAttributeResolver,
285+
options: RewriteHtmlAttributesOptions = {},
262286
): boolean {
287+
const attrs = options.attrs ?? ["src", "href"];
288+
const selector = options.selector ?? attrs.map((attr) => `[${attr}]`).join(", ");
263289
let modified = false;
264-
for (const el of document.querySelectorAll("[src], [href]")) {
265-
for (const attr of ["src", "href"]) {
290+
for (const el of document.querySelectorAll(selector)) {
291+
for (const attr of attrs) {
266292
const val = (el.getAttribute(attr) || "").trim();
267293
if (!val) continue;
268-
const archivePath = tryResolveExternal(ctx, val, referrerAbsDir);
294+
const archivePath = resolveTarget(val, referrerAbsDir);
269295
if (!archivePath) continue;
270296
el.setAttribute(attr, posix.relative(posix.dirname(entryPath), archivePath));
271297
modified = true;
@@ -305,7 +331,9 @@ function rewriteStyleBlocks(
305331
function localizeHtmlEntry(ctx: ExternalAssetContext, entryPath: string, content: Buffer): void {
306332
const referrerAbsDir = resolve(ctx.absProjectDir, dirname(entryPath));
307333
const { document } = parseHTML(content.toString("utf-8"));
308-
const attrsChanged = rewriteHtmlAttributes(ctx, document, referrerAbsDir, entryPath);
334+
const attrsChanged = rewriteHtmlAttributes(document, referrerAbsDir, entryPath, (val, dir) =>
335+
tryResolveExternal(ctx, val, dir),
336+
);
309337
const stylesChanged = rewriteStyleBlocks(ctx, document, referrerAbsDir, entryPath);
310338
if (attrsChanged || stylesChanged) {
311339
ctx.fileContents.set(entryPath, Buffer.from(document.toString(), "utf-8"));
@@ -350,7 +378,14 @@ export function localizeExternalAssets(
350378
return ctx.externalMap.size;
351379
}
352380

353-
export function createPublishArchive(projectDir: string): PublishArchiveResult {
381+
/**
382+
* Walk the project dir, read every non-ignored file, and localize external
383+
* (out-of-project) asset references. Returns the in-memory archive file map —
384+
* the seam `publish.ts` hooks a proxy-baking transform into (U6) between this
385+
* and `zipPublishFileMap` below. `cloud render` never sees this seam: it
386+
* keeps calling `createPublishArchive` directly.
387+
*/
388+
export function buildPublishFileMap(projectDir: string): Map<string, Buffer> {
354389
const absProjectDir = resolve(projectDir);
355390
const filePaths: string[] = [];
356391
collectProjectFiles(absProjectDir, absProjectDir, filePaths);
@@ -364,7 +399,12 @@ export function createPublishArchive(projectDir: string): PublishArchiveResult {
364399
}
365400

366401
localizeExternalAssets(absProjectDir, fileContents);
402+
return fileContents;
403+
}
367404

405+
/** Zip an in-memory archive file map (from `buildPublishFileMap`, optionally
406+
* transformed in between, e.g. by proxy baking) into the final archive buffer. */
407+
export function zipPublishFileMap(fileContents: Map<string, Buffer>): PublishArchiveResult {
368408
const archive = new AdmZip();
369409
for (const [filePath, content] of fileContents) {
370410
archive.addFile(filePath, content);
@@ -376,6 +416,17 @@ export function createPublishArchive(projectDir: string): PublishArchiveResult {
376416
};
377417
}
378418

419+
/**
420+
* Thin composition of `buildPublishFileMap` + `zipPublishFileMap` — signature
421+
* and behavior UNCHANGED from before the U6 split. `cloud render`
422+
* (`commands/cloud/render.ts`, `maybeUploadProject`) calls this directly and
423+
* must stay byte-identical (never see baked proxies); only `publish.ts` calls
424+
* the two halves separately with a baking transform in between.
425+
*/
426+
export function createPublishArchive(projectDir: string): PublishArchiveResult {
427+
return zipPublishFileMap(buildPublishFileMap(projectDir));
428+
}
429+
379430
export function getPublishApiBaseUrl(): string {
380431
return (
381432
process.env["HYPERFRAMES_PUBLISHED_PROJECTS_API_URL"] ||
@@ -513,6 +564,14 @@ export interface PublishOptions {
513564
projectId?: string;
514565
/** Shared team space id, sent as X-Space-Id so team members converge. Only when authenticated. */
515566
spaceId?: string;
567+
/**
568+
* Pre-built archive to upload instead of building one fresh from
569+
* `projectDir` via `createPublishArchive`. `publish.ts` passes this so it
570+
* can bake proxies into the file map between `buildPublishFileMap` and
571+
* `zipPublishFileMap` (U6); callers that omit it (e.g. `feedback`'s
572+
* minimal-repro publish) keep today's behavior unchanged.
573+
*/
574+
archive?: PublishArchiveResult;
516575
}
517576

518577
export async function publishProjectArchive(
@@ -521,7 +580,7 @@ export async function publishProjectArchive(
521580
): Promise<PublishedProjectResponse> {
522581
const isPublic = opts.public === true;
523582
const title = basename(projectDir);
524-
const archive = createPublishArchive(projectDir);
583+
const archive = opts.archive ?? createPublishArchive(projectDir);
525584
const apiBaseUrl = getPublishApiBaseUrl();
526585
const credential = await tryResolveCredential();
527586
const authHeaders = credential ? buildAuthHeaders(credential) : {};

0 commit comments

Comments
 (0)