Files
hyperframes/packages/core/src/compiler/htmlCompiler.ts
T
Miguel Ángel 621ddd4693 fix(studio): stop file names with %, apostrophes or $ from breaking Studio (#5156)
* fix(studio): serve files whose name has a bare percent sign

A browser sends src="100%.png" with the % unescaped, and decoding the whole path threw, so Studio answered 500. Only well-formed escapes are decoded now.

* fix(cli): serve files with a bare percent sign from the check and snapshot server

One shared decode rule for request paths; the image thumbnail route's malformed-escape 400 could no longer fire, so a name that is not a file is a 404.

* fix(cli): name a failed file with a bare percent sign in check

* fix(studio): keep apostrophes and dollar signs in file names when editing attributes

An attribute value is matched by its own quote kind, so src="it's.png" is replaced instead of duplicated, and every insert uses a function replacer, so $1 or $& in a file name is written as is.

* fix(studio): rename references spelled with %20 or & and read quoted media sources

WIP: not yet tested; see the resume note.

* fix(studio): match whole attribute names when editing media sources

* fix(studio): compare decoded names and escape replacement references

* fix(studio): preserve file references across URL and string consumers

* docs: clarify raw file references and URL fields

* fix(studio): keep raw path identity distinct from URL spelling

* fix: share attribute grammar and decode media URLs at their readers

* fix: preserve local filename identity in HTML URL output

* fix: decode entity references before rename candidate matching

* style: format rename entity handling and regressions

* fix: preserve platform file identity when renaming references

* fix(core): decode CSS escapes before rebasing asset URLs

* fix(core): consume CSS continuations before URL encoding

* fix(core): preserve CSS URL identity and escape rebased suffixes

* fix(core): express CSS suffix controls with Unicode categories

* fix(core): preserve URL backslash identity while rebasing

* test(core): respect platform backslash filename semantics

* fix(studio): a dropped file with %, # or ? in its name loads, and an encoded reference renames

* fix(studio): read an authored src as a URL so dropped files with spaces, %, # or ? load

* fix(studio): media routes find files named with ? or #, and the probe reads a src as a URL

* fix(studio-server): one rule for request file paths, so loudness finds files named with %, # or ?

* chore: drop the design note from the change

* fix(core): rename replaced clips whose src is URL-encoded
2026-10-08 16:37:49 +00:00

102 lines
3.3 KiB
TypeScript

import { resolve } from "path";
import { decodedUrlPath } from "@hyperframes/parsers/asset-paths";
import {
compileTimingAttrs,
injectDurations,
extractResolvedMedia,
clampDurations,
shouldClampResolvedMediaDuration,
type ResolvedDuration,
} from "./timingCompiler";
/**
* Callback to probe media duration. If not provided, media duration resolution is skipped.
* Return duration in seconds, or 0 if unknown.
*/
export type MediaDurationProber = (src: string) => Promise<number>;
function resolveMediaSrc(src: string, projectDir: string): string {
return src.startsWith("http://") || src.startsWith("https://")
? src
: resolve(projectDir, decodedUrlPath(src));
}
/**
* Compile HTML with full duration resolution.
*
* 1. Static pass: compileTimingAttrs() adds data-end where data-duration exists
* 2. For unresolved video/audio (no data-duration): probe via probeMediaDuration, inject durations
* 3. For pre-resolved audio: clamp data-duration to playable source when needed.
* Explicit video slots are preserved and hold their final frame.
*
* @param rawHtml - The raw HTML string
* @param projectDir - The project directory for resolving relative paths
* @param probeMediaDuration - Optional callback to probe media duration (e.g., via ffprobe)
*/
export async function compileHtml(
rawHtml: string,
projectDir: string,
probeMediaDuration?: MediaDurationProber,
): Promise<string> {
const { html: staticCompiled, unresolved } = compileTimingAttrs(rawHtml);
let html = staticCompiled;
if (!probeMediaDuration) return html;
// Phase 1: Resolve missing durations
const mediaUnresolved = unresolved.filter(
(el) => el.tagName === "video" || el.tagName === "audio",
);
if (mediaUnresolved.length > 0) {
const resolutions: ResolvedDuration[] = [];
for (const el of mediaUnresolved) {
if (!el.src) continue;
const src = resolveMediaSrc(el.src, projectDir);
const fileDuration = await probeMediaDuration(src);
if (fileDuration <= 0) continue;
const effectiveDuration = fileDuration - el.mediaStart;
const sourceDuration = effectiveDuration > 0 ? effectiveDuration : fileDuration;
resolutions.push({ id: el.id, duration: sourceDuration });
}
if (resolutions.length > 0) {
html = injectDurations(html, resolutions);
}
}
return clampProbedMedia(html, projectDir, probeMediaDuration);
}
async function clampProbedMedia(
html: string,
projectDir: string,
probeMediaDuration: MediaDurationProber,
): Promise<string> {
// Phase 2: Bound authored audio to playable source. Explicit video slots may
// outlive their source and render by holding the final frame.
const preResolved = extractResolvedMedia(html);
const clampList: ResolvedDuration[] = [];
for (const el of preResolved) {
if (!el.src) continue;
if (el.loop) continue;
const src = resolveMediaSrc(el.src, projectDir);
const fileDuration = await probeMediaDuration(src);
if (fileDuration <= 0) continue;
const maxDuration = fileDuration - el.mediaStart;
if (maxDuration > 0 && shouldClampResolvedMediaDuration(el.tagName, el.duration, maxDuration)) {
clampList.push({ id: el.id, duration: maxDuration });
}
}
if (clampList.length > 0) {
html = clampDurations(html, clampList);
}
return html;
}