@hyperframes/core 0.8.199 → 0.8.201

package/dist/audioAnalysis.d.ts

@@ -3,6 +3,7 @@
  * Pure functions of PCM samples, so they run the same in Node, Bun and the browser. Times are seconds into the signal.
  */
 import type { AudioAnalysisProvider } from "./audioAnalysisLadder.js";
+import { type Steps } from "./audioSteps.js";
 /** Decoded audio: one Float32Array per channel, all the same length. */
 export interface AudioSignal {
     sampleRate: number;
@@ -102,6 +103,7 @@ export interface KindFeatures {
 export declare const signalDuration: (signal: AudioSignal) => number;
 /** Per-sample energy. Channels are squared first, so a reversed channel stays audible. */
 export declare function energyMix(signal: AudioSignal): Float32Array;
+export declare function energyMixSteps(signal: AudioSignal): Steps<Float32Array>;
 export declare function envelope(signal: AudioSignal, options?: EnvelopeOptions): Envelope;
 export declare function onsets(signal: AudioSignal, options?: OnsetOptions): Onsets;
 export declare function moments(signal: AudioSignal, options?: MomentOptions): Moments | null;

package/dist/audioAnalysis.js

@@ -2,6 +2,7 @@
  * Measurements of decoded audio over time: an energy envelope, onsets, the moments a sound lands, loudness and silence.
  * Pure functions of PCM samples, so they run the same in Node, Bun and the browser. Times are seconds into the signal.
  */
+import { finish } from "./audioSteps.js";
 import { fft } from "./fft.js";
 import { rhythm } from "./audioRhythm.js";
 import { sections } from "./audioSections.js";
@@ -9,18 +10,26 @@ const DB_FLOOR = -120;
 export const signalDuration = (signal) => (signal.channels[0]?.length ?? 0) / signal.sampleRate;
 /** Per-sample energy. Channels are squared first, so a reversed channel stays audible. */
 export function energyMix(signal) {
+    return finish(energyMixSteps(signal));
+}
+const MIX_SAMPLES_PER_STEP = 65536;
+export function* energyMixSteps(signal) {
     const [first, ...rest] = signal.channels;
     if (!first)
         return new Float32Array(0);
     if (!rest.length)
         return first;
     const mixed = new Float32Array(first.length);
-    for (const channel of signal.channels)
-        for (let i = 0; i < mixed.length; i++)
-            mixed[i] += channel[i] * channel[i];
     const scale = 1 / signal.channels.length;
-    for (let i = 0; i < mixed.length; i++)
-        mixed[i] = Math.sqrt(mixed[i] * scale);
+    for (let start = 0; start < mixed.length; start += MIX_SAMPLES_PER_STEP) {
+        const end = Math.min(mixed.length, start + MIX_SAMPLES_PER_STEP);
+        for (const channel of signal.channels)
+            for (let i = start; i < end; i++)
+                mixed[i] += channel[i] * channel[i];
+        for (let i = start; i < end; i++)
+            mixed[i] = Math.sqrt(mixed[i] * scale);
+        yield;
+    }
     return mixed;
 }
 const toDb = (amplitude) => amplitude > 0 ? Math.max(DB_FLOOR, 20 * Math.log10(amplitude)) : DB_FLOOR;

package/dist/audioGroups.d.ts

@@ -100,13 +100,9 @@ export declare function audioGroupOf(el: Element): string | null;
 /**
  * Make `<hf-audio-group>` inert, once per document.
  *
- * The element is metadata — an id, a label, a chain, an automation lane — and
- * carries no content, but "no content" is not "no box": it is still an unknown
- * custom element, so in a flex or grid composition root it counts as an item
- * (taking a `gap`, shifting `justify-content`, moving every `:nth-child` after
- * it), and in inline formatting it can still open a line box. Authored layout
- * would shift by adding a group, which is not something a mixing decision is
- * allowed to do.
+ * An unknown custom element still makes a box (a flex or grid item, a line box), and a
+ * mixing decision must not shift authored layout. `contents`, not `none`: what sits
+ * inside one (a self-closed `<hf-audio-group />` takes in every later sibling) still renders, unless muted.
  *
  * `!important` because an author rule can outrank a bare type selector on
  * specificity — inertness here is a contract, not a default. Emitted from the

package/dist/audioGroups.js

@@ -199,13 +199,9 @@ function isGroupableMember(el) {
 /**
  * Make `<hf-audio-group>` inert, once per document.
  *
- * The element is metadata — an id, a label, a chain, an automation lane — and
- * carries no content, but "no content" is not "no box": it is still an unknown
- * custom element, so in a flex or grid composition root it counts as an item
- * (taking a `gap`, shifting `justify-content`, moving every `:nth-child` after
- * it), and in inline formatting it can still open a line box. Authored layout
- * would shift by adding a group, which is not something a mixing decision is
- * allowed to do.
+ * An unknown custom element still makes a box (a flex or grid item, a line box), and a
+ * mixing decision must not shift authored layout. `contents`, not `none`: what sits
+ * inside one (a self-closed `<hf-audio-group />` takes in every later sibling) still renders, unless muted.
  *
  * `!important` because an author rule can outrank a bare type selector on
  * specificity — inertness here is a contract, not a default. Emitted from the
@@ -217,6 +213,6 @@ export function ensureAudioGroupInertStyle(doc) {
         return;
     const style = doc.createElement("style");
     style.id = styleId;
-    style.textContent = `${HF_AUDIO_GROUP_TAG}{display:none!important}`;
+    style.textContent = `${HF_AUDIO_GROUP_TAG}{display:contents!important}${HF_AUDIO_GROUP_TAG}[data-hidden]{display:none!important}`;
     doc.head.appendChild(style);
 }

package/dist/audioResample.d.ts

@@ -1,2 +1,4 @@
 /** Band-limited resampling by windowed-sinc interpolation, so analysis reads the same at any decode rate. */
+import { type Steps } from "./audioSteps.js";
 export declare function resample(samples: Float32Array, from: number, to: number): Float32Array;
+export declare function resampleSteps(samples: Float32Array, from: number, to: number): Steps<Float32Array>;

package/dist/audioResample.js

@@ -1,4 +1,5 @@
 /** Band-limited resampling by windowed-sinc interpolation, so analysis reads the same at any decode rate. */
+import { finish } from "./audioSteps.js";
 const ZERO_CROSSINGS = 8;
 const STEPS_PER_CROSSING = 256;
 /** Cutoff as a share of the lower Nyquist, leaving the window's transition band below it. */
@@ -19,6 +20,10 @@ function kernelAt(x) {
     return KERNEL[i] * (1 - frac) + KERNEL[i + 1] * frac;
 }
 export function resample(samples, from, to) {
+    return finish(resampleSteps(samples, from, to));
+}
+const SAMPLES_PER_STEP = 4096;
+export function* resampleSteps(samples, from, to) {
     if (from === to)
         return samples;
     const ratio = to / from;
@@ -26,6 +31,8 @@ export function resample(samples, from, to) {
     const reach = ZERO_CROSSINGS / scale;
     const out = new Float32Array(Math.floor(samples.length * ratio));
     for (let n = 0; n < out.length; n++) {
+        if (n % SAMPLES_PER_STEP === 0)
+            yield;
         const t = n / ratio;
         const last = Math.min(samples.length - 1, Math.floor(t + reach));
         let sum = 0;

package/dist/audioRhythm.d.ts

@@ -3,6 +3,7 @@
  * tempo with a log-normal prior, and dynamic-programming beat placement (Ellis 2007). Times are seconds into the signal.
  */
 import type { AudioSignal } from "./audioAnalysis.js";
+import { type Steps } from "./audioSteps.js";
 export interface Beats {
     /** Empty when there is no steady beat, with `reason` saying so. */
     times: number[];
@@ -46,3 +47,5 @@ export declare function tempoOf(times: readonly number[]): Tempo;
 /** Band energies of `signal`, computed once per signal for every capability that reads them. */
 export declare function bandFramesOf(signal: AudioSignal): BandFrames;
 export declare function rhythm(signal: AudioSignal): Rhythm;
+/** `rhythm`, yielding between short pieces of work. */
+export declare function rhythmSteps(signal: AudioSignal): Steps<Rhythm>;

package/dist/audioRhythm.js

@@ -2,7 +2,8 @@
  * Beats, downbeats and tempo from signal processing alone: a log-band spectral-flux onset curve, an autocorrelation
  * tempo with a log-normal prior, and dynamic-programming beat placement (Ellis 2007). Times are seconds into the signal.
  */
-import { resample } from "./audioResample.js";
+import { resampleSteps } from "./audioResample.js";
+import { finish } from "./audioSteps.js";
 import { fft } from "./fft.js";
 /** Every signal is analyzed at this rate and as the mean of its channels' power, so decode rate and layout cannot change a result. */
 const ANALYSIS_RATE = 22050;
@@ -45,7 +46,7 @@ function addFramePower(samples, center, window, edges, into) {
     }
 }
 /** Per-band log power of every frame, averaged over channels so a polarity-flipped channel cannot cancel. */
-function bandPower(channels) {
+function* bandPower(channels) {
     const window = hann(FRAME_SIZE);
     const edges = bandEdges();
     const hop = ANALYSIS_RATE / FRAMES_PER_SECOND;
@@ -55,6 +56,7 @@ function bandPower(channels) {
         for (const channel of channels)
             addFramePower(channel, Math.round(f * hop), window, edges, power);
         bands.push(power.map((p) => Math.log1p((1e9 * p) / channels.length)));
+        yield;
     }
     return bands;
 }
@@ -65,7 +67,7 @@ const PITCH_CLASS = Array.from({ length: CHROMA_SIZE / 2 }, (_, bin) => {
         return -1;
     return (((Math.round(12 * Math.log2(hz / 440)) + 9) % 12) + 12) % 12;
 });
-function chromaFrames(channels) {
+function* chromaFrames(channels) {
     const window = hann(CHROMA_SIZE);
     const hop = ANALYSIS_RATE / CHROMA_FPS;
     const re = new Float64Array(CHROMA_SIZE);
@@ -87,15 +89,18 @@ function chromaFrames(channels) {
             });
         }
         frames.push(chroma);
+        yield;
     }
     return frames;
 }
-function bandFrames(signal) {
-    const channels = signal.channels.map((c) => resample(c, signal.sampleRate, ANALYSIS_RATE));
+function* bandFrames(signal) {
+    const channels = [];
+    for (const c of signal.channels)
+        channels.push(yield* resampleSteps(c, signal.sampleRate, ANALYSIS_RATE));
     return {
         fps: FRAMES_PER_SECOND,
-        bands: bandPower(channels),
-        chroma: chromaFrames(channels),
+        bands: yield* bandPower(channels),
+        chroma: yield* chromaFrames(channels),
         chromaFps: CHROMA_FPS,
     };
 }
@@ -182,7 +187,7 @@ function smoothed(curve, period) {
     });
 }
 /** Ellis's recursion: each frame's best score from a predecessor about one period back, penalized by log deviation. */
-function cumulativeScore(local, periodAt) {
+function* cumulativeScore(local, periodAt) {
     const score = new Float64Array(local.length);
     const back = new Int32Array(local.length).fill(-1);
     for (let i = 0; i < local.length; i++) {
@@ -196,6 +201,7 @@ function cumulativeScore(local, periodAt) {
         }
         score[i] = local[i] + Math.max(0, best);
         back[i] = best > 0 ? from : -1;
+        yield;
     }
     return { score, back };
 }
@@ -226,7 +232,7 @@ function trimmed(beats, local) {
 }
 const LOCAL_WINDOW_SECONDS = 8;
 /** The period through the piece: eight-second windows a second apart, held within 10% of the global period, median-smoothed. */
-function localPeriods(curve, fps, period) {
+function* localPeriods(curve, fps, period) {
     const window = Math.round(LOCAL_WINDOW_SECONDS * fps);
     const hop = Math.round(fps);
     const range = {
@@ -239,6 +245,7 @@ function localPeriods(curve, fps, period) {
         const end = Math.min(curve.length, start + window);
         periods.push(beatPeriod(curve.subarray(start, end), fps, range).period);
         centres.push((start + end) / 2);
+        yield;
     }
     const median = periods.map((_, i) => {
         const near = periods.slice(Math.max(0, i - 2), i + 3).sort((a, b) => a - b);
@@ -256,9 +263,10 @@ function interpolate(xs, ys, x) {
         }
     return ys[ys.length - 1];
 }
-function beatFrames(curve, fps, period) {
+function* beatFrames(curve, fps, period) {
     const local = smoothed(curve, period);
-    const { score, back } = cumulativeScore(local, localPeriods(curve, fps, period));
+    const periodAt = yield* localPeriods(curve, fps, period);
+    const { score, back } = yield* cumulativeScore(local, periodAt);
     const beats = [];
     for (let i = lastBeat(score); i >= 0; i = back[i])
         beats.push(i);
@@ -352,14 +360,16 @@ export const STEADY_BEAT_CONFIDENCE = 0.15;
 /** Clarity of the period, scaled down when the beats are under three times as strong as the onsets around them. */
 const beatConfidence = (clarity, lift) => round(Math.max(0, Math.min(1, clarity)) * Math.max(0, Math.min(1, lift / 3)));
 /** Beats and downbeats of `frames`, a signal's band energies and chroma. */
-function rhythmOf(frames) {
+function* rhythmOf(frames) {
     const curves = onsetCurves(frames);
+    yield;
     const { period, clarity } = beatPeriod(curves.broad, curves.fps);
+    yield;
     if (curves.broad.length < SHORTEST_SECONDS * curves.fps)
         return noRhythm(0, "too short for a steady beat");
     if (!curves.broad.some((v) => v > 0) || curves.broad.length < 2 * period)
         return noRhythm(0);
-    const { frames: beatList, local } = beatFrames(curves.broad, curves.fps, period);
+    const { frames: beatList, local } = yield* beatFrames(curves.broad, curves.fps, period);
     const confidence = beatConfidence(clarity, onsetLift(beatList, local));
     if (beatList.length < 4 || confidence < STEADY_BEAT_CONFIDENCE)
         return noRhythm(confidence);
@@ -393,15 +403,22 @@ export function tempoOf(times) {
     return { value: bpm(interval), curve };
 }
 const measured = new WeakMap();
-/** Band energies of `signal`, computed once per signal for every capability that reads them. */
-export function bandFramesOf(signal) {
+function* measuredSteps(signal) {
     let entry = measured.get(signal);
     if (!entry)
-        measured.set(signal, (entry = { frames: bandFrames(signal) }));
-    return entry.frames;
+        measured.set(signal, (entry = { frames: yield* bandFrames(signal) }));
+    return entry;
+}
+/** Band energies of `signal`, computed once per signal for every capability that reads them. */
+export function bandFramesOf(signal) {
+    return finish(measuredSteps(signal)).frames;
 }
 export function rhythm(signal) {
-    const frames = bandFramesOf(signal);
-    const entry = measured.get(signal);
-    return (entry.rhythm ??= rhythmOf(frames));
+    return finish(rhythmSteps(signal));
+}
+/** `rhythm`, yielding between short pieces of work. */
+export function* rhythmSteps(signal) {
+    const entry = yield* measuredSteps(signal);
+    entry.rhythm ??= yield* rhythmOf(entry.frames);
+    return entry.rhythm;
 }

package/dist/audioSteps.d.ts

@@ -0,0 +1,3 @@
+/** A long computation that yields between short pieces of work, so a caller can pause it. */
+export type Steps<T> = Generator<void, T, void>;
+export declare function finish<T>(steps: Steps<T>): T;

package/dist/audioSteps.js

@@ -0,0 +1,7 @@
+export function finish(steps) {
+    for (;;) {
+        const next = steps.next();
+        if (next.done)
+            return next.value;
+    }
+}

package/dist/beats/beatDetection.js

@@ -1,5 +1,6 @@
-import { energyMix } from "../audioAnalysis.js";
-import { bandFramesOf, rhythm, tempoOf } from "../audioRhythm.js";
+import { energyMixSteps } from "../audioAnalysis.js";
+import { rhythmSteps, tempoOf } from "../audioRhythm.js";
+import { finish } from "../audioSteps.js";
 const STRENGTH_WINDOW_S = 0.05; // ±50ms RMS window
 /** Local RMS amplitude at a given audio-file time. */
 export function computeRmsAt(channelData, sampleRate, time) {
@@ -28,14 +29,27 @@ function beatStrengths(beats, levels, sampleRate) {
     const peak = Math.max(...energies, 1e-6);
     return { strengths: energies.map((e) => Math.min(1, e / peak)), peak };
 }
+/** Longest stretch the analysis runs before awaiting `pause`. */
+const SLICE_MS = 8;
+async function sliced(steps, pause) {
+    if (!pause)
+        return finish(steps);
+    let start = performance.now();
+    for (;;) {
+        const next = steps.next();
+        if (next.done)
+            return next.value;
+        if (performance.now() - start >= SLICE_MS) {
+            await pause();
+            start = performance.now();
+        }
+    }
+}
 /** Beats, tempo and per-beat strength of decoded audio; no beats and a null bpm when it has no steady beat. */
 export async function analyzeMusicFromSignal(signal, { pause } = {}) {
     await pause?.();
-    bandFramesOf(signal);
-    await pause?.();
-    const { beats } = rhythm(signal);
-    await pause?.();
-    const channelData = energyMix(signal);
+    const { beats } = await sliced(rhythmSteps(signal), pause);
+    const channelData = await sliced(energyMixSteps(signal), pause);
     const confidence = beats.confidence ?? 0;
     const times = beats.times;
     const { strengths, peak } = beatStrengths(times, channelData, signal.sampleRate);
@@ -55,6 +69,7 @@ export function analyzeMusicFromBuffer(audioBuffer, options = {}) {
     return analyzeMusicFromSignal({ sampleRate: audioBuffer.sampleRate, channels }, options);
 }
 export async function analyzeMusicFromUrl(url, options = {}) {
+    await options.pause?.();
     const audioContext = new AudioContext();
     try {
         const response = await fetch(url);

package/dist/compiler/htmlBundler.js

@@ -16,6 +16,7 @@ import { resolve, relative, dirname, isAbsolute, sep } from "path";
 import { extractStandaloneEntryFromIndex, isTemplateEntry } from "./standaloneEntry.js";
 import { decodeCssEscapes, decodeWellFormedEscapes, encodeUrlPath, decodedUrlPath, splitUrlSuffix, } from "@hyperframes/parsers/asset-paths";
 import { CSS_URL_RE, isNonRelativeUrl } from "./assetPaths.js";
+import { rewriteSrcsetUrls } from "./srcset.js";
 import { compileHtml } from "./htmlCompiler.js";
 import { RUNTIME_BOOTSTRAP_ATTR, escapeInlineScriptSource, insertRuntimeTag, parseHTMLContent, stripEmbeddedRuntimeScripts, } from "./htmlDocument.js";
 // rewriteSubCompPaths functions are used by inlineSubCompositions (shared module)
@@ -23,7 +24,7 @@ import { buildVariablesByCompScript, dedupeFontFaceRules, hoistFontFaceRules, sc
 import { validateHyperframeHtmlContract } from "./staticGuard.js";
 import { getHyperframeRuntimeScript } from "../generated/runtime-inline.js";
 import { readDeclaredDefaults } from "../runtime/getVariables.js";
-import { ensureExternalLinkTag, inlineSubCompositions, refuseSwapsReachedByRootScripts, } from "./inlineSubCompositions.js";
+import { ensureExternalLinkTag, inlineSubCompositions, isLibraryCopy, refuseSwapsReachedByRootScripts, } from "./inlineSubCompositions.js";
 import { isSafePath, resolveWithinProject } from "../safePath.js";
 import { ensureHfIds } from "@hyperframes/parsers/hf-ids";
 import { HF_COLOR_GRADING_ATTR } from "../colorGrading.js";
@@ -125,43 +126,6 @@ function rebaseRelativePath(urlValue, fromDir, toDir) {
     const rebased = encodeUrlPath(relative(resolve(toDir), absolutePath).split(sep).join("/"));
     return appendSuffixToUrl(rebased, suffix);
 }
-function rewriteSrcsetUrls(srcset, rewriteUrl) {
-    const parts = [];
-    let position = 0;
-    let written = 0;
-    // Preserve URL commas per https://html.spec.whatwg.org/multipage/images.html#parse-a-srcset-attribute
-    while (position < srcset.length) {
-        while (position < srcset.length && /[ \t\n\r\f,]/.test(srcset.charAt(position)))
-            position++;
-        const start = position;
-        while (position < srcset.length && !/[ \t\n\r\f]/.test(srcset.charAt(position)))
-            position++;
-        let end = position;
-        while (end > start && srcset.charAt(end - 1) === ",")
-            end--;
-        if (end > start) {
-            const url = srcset.slice(start, end);
-            const rewritten = rewriteUrl(url);
-            if (rewritten !== url) {
-                parts.push(srcset.slice(written, start), rewritten);
-                written = end;
-            }
-        }
-        if (end < position)
-            continue;
-        let inParens = false;
-        while (position < srcset.length) {
-            const char = srcset.charAt(position++);
-            if (char === "(")
-                inParens = true;
-            else if (char === ")")
-                inParens = false;
-            else if (char === "," && !inParens)
-                break;
-        }
-    }
-    return parts.length > 0 ? parts.join("") + srcset.slice(written) : srcset;
-}
 function rebaseColorGradingLutPath(value, fromDir, toDir) {
     if (!value.trim().startsWith("{"))
         return value;
@@ -966,7 +930,8 @@ async function bundleProject(projectDir, options) {
         ].map((el) => {
             const src = el.getAttribute("src");
             const path = src && isRelativeUrl(src) ? resolveEntryUrl(src) : null;
-            return src ? (path && safeReadFile(path)) || "" : el.textContent || "";
+            const text = src ? (path && safeReadFile(path)) || "" : el.textContent || "";
+            return isLibraryCopy(text) ? "" : text;
         })
         : [];
     // Inline sub-compositions (via shared function)
@@ -1006,6 +971,10 @@ async function bundleProject(projectDir, options) {
         },
         flattenInnerRoot: prepareFlattenedInnerRoot,
         tagScenes: options?.sceneParts === true,
+        readProjectScript: (path) => {
+            const resolved = isRelativeUrl(path) ? resolveEntryUrl(path) : null;
+            return resolved ? safeReadFile(resolved) : null;
+        },
         readVariableDefaults: readDeclaredDefaults,
         parseHostVariables: parseHostVariableValues,
         buildScopeSelector: (compId) => cssAttributeSelector("data-composition-id", compId),
@@ -1025,6 +994,10 @@ async function bundleProject(projectDir, options) {
         ...subCompResult.variablesByComp,
     };
     const seenCompScriptSrcs = new Set();
+    const scenesBySrc = new Map();
+    for (const item of subCompResult.scriptItems)
+        if (item.kind !== "inline")
+            scenesBySrc.set(item.src, (scenesBySrc.get(item.src) ?? new Set()).add(item.scene));
     for (const scriptItem of subCompResult.scriptItems) {
         if (scriptItem.kind === "inline") {
             pushRun(scriptRuns, scriptItem.scene, scriptItem.content);
@@ -1039,12 +1012,14 @@ async function bundleProject(projectDir, options) {
         if (seenCompScriptSrcs.has(extSrc))
             continue;
         seenCompScriptSrcs.add(extSrc);
+        // Run once for the film when scenes share it: a scene mounts without the one that loaded it first.
+        const scene = (scenesBySrc.get(extSrc)?.size ?? 0) > 1 ? undefined : scriptItem.scene;
         if (isRelativeUrl(extSrc) && scriptItem.type !== "module") {
             const jsPath = resolveEntryUrl(extSrc);
             const js = jsPath ? safeReadFile(jsPath) : null;
             if (js != null) {
                 const chunk = () => preserveLocalScriptIntegrity(document, extSrc, resolveEntryUrl) ? "" : js;
-                pushRun(scriptRuns, scriptItem.scene, chunk);
+                pushRun(scriptRuns, scene, chunk);
                 continue;
             }
         }

package/dist/compiler/inlineSubCompositions.d.ts

@@ -11,6 +11,7 @@ import { type CompositionStyle } from "./scriptRuns.js";
  * `data-composition-file`).
  */
 import { type AssetExists } from "./rewriteSubCompPaths.js";
+export declare const isLibraryCopy: (script: string) => boolean;
 /** Marks each scene whose nodes a script outside it names by selector, id or class: a swap would strand it. */
 export declare function refuseSwapsReachedByRootScripts(document: Document, rootScripts: string[]): void;
 export interface InlineSubCompositionsOptions {
@@ -98,6 +99,7 @@ export interface InlineSubCompositionsOptions {
     onMissingComposition?: (srcPath: string, reason?: string) => void;
     /** Tag each top-level host with `data-hf-scene` and report every part's scene, for preview swaps. */
     tagScenes?: boolean;
+    readProjectScript?: (path: string) => string | null;
 }
 export interface ExternalLink {
     href: string;

package/dist/compiler/inlineSubCompositions.js

@@ -20,15 +20,74 @@ import { enumerateNestedCompositionHosts, planCompositionAssembly, extractedComp
 import { SCENE_NO_SWAP_ATTR, SCENE_PART_ATTR } from "../sceneParts.js";
 // Anything a scene script can leave running, pending or registered outside its timeline, or that
 // throws when run again: only the timeline is torn down when a scene is swapped, so when unsure, refuse.
-const SIDE_EFFECT_RE = /\b(addEventListener|requestAnimationFrame|requestIdleCallback|setTimeout|setInterval|queueMicrotask|getContext|WebGL\w*|WebGPU\w*|gpu|Worker|WebSocket|EventSource|Audio\w*|\w*Observer|fetch|import|eval|Function|Promise|async|await|delayedCall|ScrollTrigger|Draggable|anime|customElements|registerProperty|addListener|BroadcastChannel|pushState|replaceState|adoptedStyleSheets|documentElement|getElementsByTagName|lottie|THREE|__hf[A-Z]\w*)\b|\.then\s*\(|\.animate\s*\(|\.ticker\b|repeat\s*:\s*-1|\.repeat\s*\(\s*-1|defineProperty\s*\(\s*(window|globalThis|self|document)\b|\bfonts\s*\.\s*add\b|\.on[a-z]+\s*=(?!=)|\bon(resize|scroll|message|key\w+|click|pointer\w+|mouse\w+|wheel|visibilitychange|hashchange|popstate|error|load)\s*=(?!=)|\[\s*["']on[a-z]+["']\s*\]|document\s*\.\s*(head|body)\b|querySelector(All)?\(\s*["'](head|body)["']|\bgsap\s*\.\s*(?:to|from|fromTo)\s*\(|\bgsap\s*\.\s*timeline\s*\((?:[^()]|\([^()]*\))*\)\s*\.\s*(?:to|from|fromTo|set|add|call)\s*\(/;
+const SIDE_EFFECT_RE = /\b(addEventListener|requestAnimationFrame|requestIdleCallback|setTimeout|setInterval|queueMicrotask|getContext|WebGL\w*|WebGPU\w*|gpu|Worker|WebSocket|EventSource|Audio\w*|\w*Observer|fetch|import|eval|Function|Promise|async|await|delayedCall|ScrollTrigger|Draggable|anime|customElements|registerProperty|addListener|BroadcastChannel|pushState|replaceState|adoptedStyleSheets|documentElement|getElementsByTagName|lottie|THREE|__hf[A-Z]\w*)\b|\.then\s*\(|\.ticker\b|repeat\s*:\s*-1|\.repeat\s*\(\s*-1|defineProperty\s*\(\s*(window|globalThis|self|document)\b|\bfonts\s*\.\s*add\b|\.on[a-z]+\s*=(?!=)|\bon(resize|scroll|message|key\w+|click|pointer\w+|mouse\w+|wheel|visibilitychange|hashchange|popstate|error|load)\s*=(?!=)|\[\s*["']on[a-z]+["']\s*\]|document\s*\.\s*(head|body)\b|querySelector(All)?\(\s*["'](head|body)["']|\bgsap\s*\.\s*(?:to|from|fromTo)\s*\(|\bgsap\s*\.\s*timeline\s*\((?:[^()]|\([^()]*\))*\)\s*\.\s*(?:to|from|fromTo|set|add|call)\s*\(/;
 // npm packages that only define globals when loaded; lottie-web is absent because it scans the page on load.
 const SWAP_SAFE_LIBRARY_URL = /^https:\/\/(cdn\.jsdelivr\.net\/npm|unpkg\.com)\/(gsap|three|d3|d3-[a-z-]+|topojson-client|clipper-lib)(@[^/]+)?\//;
 const isSwapSafeLibrary = (src) => URL.canParse(src) && SWAP_SAFE_LIBRARY_URL.test(new URL(src).href);
+// GSAP's published file copied into a project, known by its license banner: it only defines globals too.
+const GSAP_BANNER_RE = /^\s*\/\*!\s*\*\s*GSAP \d+\.\d+\.\d+\s*\*\s*https:\/\/gsap\.com\b/;
+export const isLibraryCopy = (script) => GSAP_BANNER_RE.test(script);
+// Waits on the page's fonts, ready or loading named faces: each settles once, leaving nothing behind.
+const STRING_ARG = String.raw `(?:"(?:\\.|[^"\\\n])*"|'(?:\\.|[^'\\\n])*')`;
+const FONT_LOAD = String.raw `document\s*\.\s*fonts\s*\.\s*load\s*\(\s*${STRING_ARG}\s*(?:,\s*${STRING_ARG}\s*)?\)`;
+const FONT_PROMISE = String.raw `(?:document\s*\.\s*fonts\s*\.\s*ready\b|${FONT_LOAD}|Promise\s*\.\s*all\s*\(\s*\[\s*${FONT_LOAD}(?:\s*,\s*${FONT_LOAD})*\s*,?\s*\]\s*\))`;
+const FONT_WAIT_RE = new RegExp(String.raw `\b${FONT_PROMISE}\s*\.\s*then\s*\(|\bawait\s+${FONT_PROMISE}`, "g");
+// A canvas made only to measure text: never named, so nothing attaches it to the page or draws on it there.
+const TEXT_MEASURE_CANVAS_RE = /\bdocument\s*\.\s*createElement\s*\(\s*(["'])canvas\1\s*\)\s*\.\s*getContext\s*\(\s*(["'])2d\2\s*\)/g;
+// A timeline chained as it is registered: the registry holds it, so unmounting the scene stops it.
+const REGISTERED_CHAIN_RE = /(\b(?:window\s*\.\s*)?__timelines\s*\[[^[\]]*\]\s*=\s*)gsap\s*\.\s*timeline\s*\(/g;
+/** Whether a call of the browser's Element.animate may leave an animation: it gets timing, its second argument. */
+function lastingAnimateCall(script) {
+    for (const call of script.matchAll(/\.animate\s*\(/g)) {
+        if (topLevelArgs(script, call.index + call[0].length) !== 1)
+            return true;
+    }
+    return false;
+}
+// Arguments of the call whose "(" ends before `from`; none, a spread or an unclosed call never count as one.
+function topLevelArgs(script, from) {
+    let depth = 0;
+    let args = 1;
+    if (/^\s*(\.\.\.|\))/.test(script.slice(from)))
+        return Number.POSITIVE_INFINITY;
+    for (let i = from; i < script.length; i++) {
+        const ch = script[i];
+        if (ch === '"' || ch === "'" || ch === "`") {
+            const end = script.indexOf(ch, i + 1);
+            if (end < 0)
+                return Number.POSITIVE_INFINITY;
+            i = end;
+        }
+        else if ("([{".includes(ch))
+            depth++;
+        else if (")]}".includes(ch)) {
+            if (depth === 0)
+                return args;
+            depth--;
+        }
+        else if (ch === "," && depth === 0)
+            args++;
+    }
+    return Number.POSITIVE_INFINITY;
+}
 /** Why an authored scene script cannot be swapped out cleanly, or null when it can. */
 function sceneScriptSwapRefusal(script) {
-    const match = SIDE_EFFECT_RE.exec(script);
-    return match ? `its script uses ${match[0].trim()}` : null;
+    const withoutFontWaits = script.replace(FONT_WAIT_RE, "");
+    const awaitedFontsOnly = /\bawait\b/.test(script) && !/\bawait\b/.test(withoutFontWaits);
+    let checked = (awaitedFontsOnly ? withoutFontWaits.replace(/\basync\b/g, "") : withoutFontWaits).replace(REGISTERED_CHAIN_RE, "$1(");
+    // The context hands its canvas back through .canvas, which could then reach the page.
+    if (!/\.\s*canvas\b/.test(checked))
+        checked = checked.replace(TEXT_MEASURE_CANVAS_RE, "");
+    const match = SIDE_EFFECT_RE.exec(checked);
+    if (match)
+        return `its script uses ${match[0].trim()}`;
+    return lastingAnimateCall(checked) ? "its script uses .animate(" : null;
 }
+const projectScriptRefusal = (text) => text === null
+    ? "it runs a script that is not a known library"
+    : isLibraryCopy(text)
+        ? null
+        : sceneScriptSwapRefusal(text);
 // A quoted string in a script, in any of the three quote styles.
 const STRING_LITERAL_RE = /(["'`])((?:\\.|(?!\1)[^\\\n])*?)\1/g;
 // Text ending where createElement takes its tag: that string makes a node, it selects none.
@@ -135,7 +194,7 @@ function defaultBuildScopeSelector(compId) {
  */
 // fallow-ignore-next-line complexity
 export function inlineSubCompositions(document, hosts, options) {
-    const { resolveHtml, parseHtml, hostIdentityMap, rewriteInlineStyles = false, flattenInnerRoot, compoundAuthoredRoot, readVariableDefaults, parseHostVariables, buildScopeSelector = defaultBuildScopeSelector, scriptErrorLabel = "[HyperFrames] composition script error:", onMissingComposition, assetExists, tagScenes = false, } = options;
+    const { resolveHtml, parseHtml, hostIdentityMap, rewriteInlineStyles = false, flattenInnerRoot, compoundAuthoredRoot, readVariableDefaults, parseHostVariables, buildScopeSelector = defaultBuildScopeSelector, scriptErrorLabel = "[HyperFrames] composition script error:", onMissingComposition, assetExists, tagScenes = false, readProjectScript, } = options;
     const rootStyles = [...document.querySelectorAll("style")];
     const styles = [];
     const styleScenes = [];
@@ -338,7 +397,7 @@ export function inlineSubCompositions(document, hosts, options) {
                     ? sceneScriptSwapRefusal(scriptEl.textContent || "")
                     : isSwapSafeLibrary(externalSrc)
                         ? null
-                        : "it runs a script that is not a known library");
+                        : projectScriptRefusal(readProjectScript?.(externalSrc) ?? null));
             if (type === "importmap") {
                 const map = parseImportMap(scriptEl.textContent || "", (url) => {
                     // The rebase drops a leading "./" and a trailing "/"; an import map address needs both.

package/dist/compiler/srcset.d.ts

@@ -0,0 +1 @@
+export declare function rewriteSrcsetUrls(srcset: string, rewriteUrl: (url: string) => string): string;

package/dist/compiler/srcset.js

@@ -0,0 +1,46 @@
+function skipSrcsetDescriptors(srcset, position) {
+    let inParens = false;
+    while (position < srcset.length) {
+        const char = srcset.charAt(position++);
+        if (char === "(")
+            inParens = true;
+        else if (char === ")")
+            inParens = false;
+        else if (char === "," && !inParens)
+            break;
+    }
+    return position;
+}
+function readSrcsetUrl(srcset, position) {
+    while (position < srcset.length && /[ \t\n\r\f,]/.test(srcset.charAt(position)))
+        position++;
+    const start = position;
+    while (position < srcset.length && !/[ \t\n\r\f]/.test(srcset.charAt(position)))
+        position++;
+    let end = position;
+    while (end > start && srcset.charAt(end - 1) === ",")
+        end--;
+    return { start, end, next: position };
+}
+export function rewriteSrcsetUrls(srcset, rewriteUrl) {
+    const parts = [];
+    let position = 0;
+    let written = 0;
+    // Preserve URL commas per https://html.spec.whatwg.org/multipage/images.html#parse-a-srcset-attribute
+    while (position < srcset.length) {
+        const { start, end, next } = readSrcsetUrl(srcset, position);
+        position = next;
+        if (end > start) {
+            const url = srcset.slice(start, end);
+            const rewritten = rewriteUrl(url);
+            if (rewritten !== url) {
+                parts.push(srcset.slice(written, start), rewritten);
+                written = end;
+            }
+        }
+        if (end < position)
+            continue;
+        position = skipSrcsetDescriptors(srcset, position);
+    }
+    return parts.length > 0 ? parts.join("") + srcset.slice(written) : srcset;
+}