Files
hyperframes/packages/core/src/compiler/timingCompiler.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

362 lines
12 KiB
TypeScript

/**
* Timing Compiler
*
* Shared, pure HTML compilation that normalizes timing attributes.
* Works in both Node.js and browser without a DOM.
*
* Guarantees every timed element gets:
* - id on media elements when missing
* - data-end (computed from data-start + data-duration when possible)
* - data-has-audio on <video> elements (false for muted visual-only videos)
*
* For elements without data-duration (e.g. videos relying on source duration),
* this compiler identifies them as "unresolved" so the caller can provide
* durations via an environment-specific resolver (ffprobe, el.duration, etc.)
* and call injectDurations() to complete the compilation.
*
* Relative `data-start` (`intro`, `intro + 0.5`) is not numeric — leave
* `data-end` off so extract can resolve the id-ref later.
*/
import { scanHtmlOpeningTags, decodeAuthoredAttribute } from "@hyperframes/parsers";
import { parseNumeric } from "@hyperframes/parsers/composition-contract";
import {
parseStrictFiniteTimingNumber,
readElementRateSpec,
readMediaStart,
} from "../runtime/playbackRate.js";
import type { RateSpec } from "../speedRamp.js";
// ── Types ────────────────────────────────────────────────────────────────
export interface UnresolvedElement {
id: string;
tagName: string;
src?: string;
start: number;
end?: number;
duration?: number;
mediaStart: number;
playbackRate: RateSpec;
compositionSrc?: string;
}
export interface ResolvedDuration {
id: string;
duration: number;
}
export interface ResolvedMediaElement {
id: string;
tagName: string;
src?: string;
start: number;
duration: number;
mediaStart: number;
playbackRate: RateSpec;
loop: boolean;
}
export interface CompilationResult {
html: string;
unresolved: UnresolvedElement[];
}
// ffprobe precision can differ slightly across local and CI media stacks, so
// avoid shortening authored audio for insignificant probe drift.
export const MEDIA_DURATION_CLAMP_EPSILON_SECONDS = 0.05;
export function shouldClampMediaDuration(declaredDuration: number, maxDuration: number): boolean {
return declaredDuration > maxDuration + MEDIA_DURATION_CLAMP_EPSILON_SECONDS;
}
/**
* Whether compilation should shorten an authored media slot to its source.
*
* Non-looping video intentionally keeps an explicit longer slot: browsers and
* the render frame injector hold its final frame until that authored slot ends.
* Audio has no frame to hold, so its slot remains bounded by playable source.
*/
export function shouldClampResolvedMediaDuration(
tagName: ResolvedMediaElement["tagName"],
declaredDuration: number,
maxDuration: number,
): boolean {
return tagName === "audio" && shouldClampMediaDuration(declaredDuration, maxDuration);
}
// ── Helpers ──────────────────────────────────────────────────────────────
function sourceAttribute(tag: string, name: string) {
return scanHtmlOpeningTags(tag)[0]?.attributes.find((attr) => attr.name === name);
}
function getAttr(tag: string, name: string): string | null {
return tagAttrReader(tag).getAttribute(name);
}
function tagAttrReader(tag: string): Pick<Element, "getAttribute"> {
const attributes = scanHtmlOpeningTags(tag)[0]?.attributes ?? [];
return {
getAttribute: (name) => {
const attr = attributes.find((attr) => attr.name === name);
return attr?.kind === "value" ? decodeAuthoredAttribute(attr.value) : null;
},
};
}
function hasAttr(tag: string, name: string): boolean {
return sourceAttribute(tag, name) !== undefined;
}
function injectAttr(tag: string, attr: string, value: string): string {
return tag.replace(/>$/, ` ${attr}="${value}">`);
}
function setAttr(tag: string, name: string, value: string): string {
const attr = sourceAttribute(tag, name);
if (!attr) return injectAttr(tag, name, value);
return tag.slice(0, attr.start) + `${name}="${value}"` + tag.slice(attr.end);
}
function* iterateOpeningTags(html: string, names: readonly string[]) {
for (const span of scanHtmlOpeningTags(html)) {
if (span.closed && names.includes(span.name)) {
yield { tag: html.slice(span.start, span.end), index: span.start, end: span.end };
}
}
}
function replaceOpeningTags(
html: string,
names: readonly string[],
replace: (tag: string) => string,
): string {
const parts: string[] = [];
let cursor = 0;
for (const { tag, index, end } of iterateOpeningTags(html, names)) {
parts.push(html.slice(cursor, index), replace(tag));
cursor = end;
}
parts.push(html.slice(cursor));
return parts.join("");
}
function replaceIdTags(html: string, id: string, replace: (tag: string) => string): string {
const parts: string[] = [];
let cursor = 0;
for (const span of scanHtmlOpeningTags(html)) {
if (!span.closed) continue;
const tag = html.slice(span.start, span.end);
const attr = span.attributes.find((attr) => attr.name === "id");
if (attr?.kind !== "value" || decodeAuthoredAttribute(attr.value) !== id) continue;
parts.push(html.slice(cursor, span.start), replace(tag));
cursor = span.end;
}
parts.push(html.slice(cursor));
return parts.join("");
}
function withDefaultTimingAttrs(tag: string, tagName: string, generateId: () => number) {
let result = tag;
let id = getAttr(result, "id");
if (!id) {
id = `hf-${tagName}-${generateId()}`;
result = injectAttr(result, "id", id);
}
let startStr = getAttr(result, "data-start");
if (startStr === null) {
result = injectAttr(result, "data-start", "0");
result = injectAttr(result, "data-hf-auto-start", "");
startStr = "0";
}
return { tag: result, id, start: parseNumeric(startStr) };
}
function withVideoAudioFlag(tag: string, isVideo: boolean): string {
if (!isVideo || hasAttr(tag, "data-has-audio")) return tag;
return injectAttr(tag, "data-has-audio", hasAttr(tag, "muted") ? "false" : "true");
}
function compileTag(
tag: string,
isVideo: boolean,
generateId: () => number,
): { tag: string; unresolved: UnresolvedElement | null } {
const tagName = isVideo ? "video" : "audio";
const defaults = withDefaultTimingAttrs(tag, tagName, generateId);
let result = defaults.tag;
let unresolved: UnresolvedElement | null = null;
const { id, start } = defaults;
const attrReader = tagAttrReader(result);
const mediaStart = readMediaStart(attrReader);
const playbackRate = readElementRateSpec(attrReader);
// 1. Compute data-end from data-start + data-duration. Skip relative id-refs.
if (!hasAttr(result, "data-end")) {
const durationStr = getAttr(result, "data-duration");
const duration = parseStrictFiniteTimingNumber(durationStr);
if (duration != null) {
if (start != null) {
result = injectAttr(result, "data-end", String(start + duration));
}
} else {
// No data-duration: mark as unresolved so caller can provide it
unresolved = {
id,
tagName,
src: getAttr(result, "src") ?? undefined,
start: start ?? 0,
mediaStart,
playbackRate,
};
}
}
result = withVideoAudioFlag(result, isVideo);
return { tag: result, unresolved };
}
/**
* Compile timing attributes in HTML.
*
* Phase 1 (static): Adds data-end where data-duration exists,
* adds data-has-audio on videos.
*
* Returns the compiled HTML and a list of elements that could not be
* resolved statically (missing data-duration). The caller should resolve
* these via ffprobe / el.duration and call injectDurations().
*/
export function compileTimingAttrs(html: string): CompilationResult {
const unresolved: UnresolvedElement[] = [];
let nextVideoId = 0;
let nextAudioId = 0;
// Process <video ...> tags
html = replaceOpeningTags(html, ["video"], (match) => {
const { tag, unresolved: u } = compileTag(match, true, () => nextVideoId++);
if (u) unresolved.push(u);
return tag;
});
// Process <audio ...> tags
html = replaceOpeningTags(html, ["audio"], (match) => {
const { tag, unresolved: u } = compileTag(match, false, () => nextAudioId++);
if (u) unresolved.push(u);
return tag;
});
// Identify unresolved timed elements (divs with data-start but no data-end/data-duration)
// These are typically compositions whose duration depends on GSAP timelines
for (const { tag: match } of iterateOpeningTags(html, ["div", "section"])) {
if (!hasAttr(match, "data-start")) continue;
if (hasAttr(match, "data-end") || hasAttr(match, "data-duration")) continue;
const id = getAttr(match, "id");
const compositionSrc = getAttr(match, "data-composition-src");
if (id) {
const startStr = getAttr(match, "data-start");
unresolved.push({
id,
tagName: "div",
start: parseNumeric(startStr) ?? 0,
mediaStart: 0,
playbackRate: 1,
compositionSrc: compositionSrc ?? undefined,
});
}
}
return { html, unresolved };
}
/**
* Inject resolved durations into compiled HTML.
*
* For each resolved element, adds data-duration and data-end attributes.
* Call this after resolving durations via ffprobe, el.duration, or
* GSAP timeline queries.
*/
export function injectDurations(html: string, resolutions: ResolvedDuration[]): string {
for (const { id, duration } of resolutions) {
// Match the element's opening tag by id
html = replaceIdTags(html, id, (tag) => {
let result = tag;
// Add data-duration if missing
if (parseStrictFiniteTimingNumber(getAttr(result, "data-duration")) == null) {
result = setAttr(result, "data-duration", String(duration));
}
// Add data-end if missing. Skip relative id-refs.
if (!hasAttr(result, "data-end")) {
const start = parseNumeric(getAttr(result, "data-start"));
if (start != null) {
result = injectAttr(result, "data-end", String(start + duration));
}
}
return result;
});
}
return html;
}
/**
* Extract video/audio elements that already have data-duration set.
* Used by callers to validate declared durations against actual source durations.
*/
export function extractResolvedMedia(html: string): ResolvedMediaElement[] {
const resolved: ResolvedMediaElement[] = [];
for (const { tag } of iterateOpeningTags(html, ["video", "audio"])) {
const id = getAttr(tag, "id");
const durationStr = getAttr(tag, "data-duration");
if (!id || durationStr === null) continue;
const duration = parseStrictFiniteTimingNumber(durationStr);
if (duration == null || duration <= 0) continue;
const isVideo = /^<video/i.test(tag);
const startStr = getAttr(tag, "data-start");
const attrReader = tagAttrReader(tag);
resolved.push({
id,
tagName: isVideo ? "video" : "audio",
src: getAttr(tag, "src") ?? undefined,
start: parseNumeric(startStr) ?? 0,
duration,
mediaStart: readMediaStart(attrReader),
playbackRate: readElementRateSpec(attrReader),
loop: hasAttr(tag, "loop"),
});
}
return resolved;
}
/**
* Clamp existing data-duration and data-end on media elements.
* For each resolution, replaces the declared duration with the clamped value
* and recomputes data-end accordingly.
*/
export function clampDurations(html: string, clamps: ResolvedDuration[]): string {
for (const { id, duration } of clamps) {
html = replaceIdTags(html, id, (tag) => {
// Replace data-duration value
if (hasAttr(tag, "data-duration")) tag = setAttr(tag, "data-duration", String(duration));
const start = parseNumeric(getAttr(tag, "data-start"));
if (start != null && hasAttr(tag, "data-end")) {
tag = setAttr(tag, "data-end", String(start + duration));
}
return tag;
});
}
return html;
}