@hyperframes/core 0.8.208 → 0.8.210

package/dist/index.d.ts

@@ -34,7 +34,7 @@ export { clearGifFramesBeforeNext, gifClearsAfterLeavingFrameInPlace, parseAnima
 export { HF_COLOR_GRADING_ATTR, HF_COLOR_GRADING_ADJUST_KEYS, HF_COLOR_GRADING_ACTIVE_EFFECT_KEYS, HF_COLOR_GRADING_ANIMATABLE_PROPERTIES, HF_COLOR_GRADING_CANVAS_ID_PREFIX, HF_COLOR_GRADING_COLOR_SPACE, HF_COLOR_GRADING_CURVE_KEYS, HF_COLOR_GRADING_DETAIL_KEYS, HF_COLOR_GRADING_EFFECT_APPLY_DEFAULTS, HF_COLOR_GRADING_EFFECT_KEYS, HF_COLOR_GRADING_EFFECT_PRESETS, HF_COLOR_GRADING_GRADE_PRESETS, HF_COLOR_GRADING_HUE_CURVE_KEYS, HF_COLOR_GRADING_LUT_KEYS, HF_COLOR_GRADING_PALETTES, HF_COLOR_GRADING_PRESETS, HF_COLOR_GRADING_TOP_LEVEL_KEYS, HF_COLOR_GRADING_WHEEL_KEYS, getHfColorGradingCapabilities, hasHfColorGradingAuthoredValues, isHfColorGradingActive, normalizeHfColorGrading, normalizeHfColorGradingWithVariables, resolveHfColorGradingVariables, serializeHfColorGrading, type HfColorGrading, type HfColorGradingAdjust, type HfColorGradingAdjustKey, type HfColorGradingAnimatablePath, type HfColorGradingActiveEffectKey, type HfColorGradingDetailKey, type HfColorGradingDetails, type HfColorGradingEffectKey, type HfColorGradingEffects, type HfColorGradingLutRef, type HfColorGradingPreset, type HfColorGradingPresetId, type HfColorGradingTarget, type HfColorGradingVariableMap, type HfColorGradingCapabilities, type HfColorGradingCurveKey, type HfColorGradingCurves, type HfColorGradingHueCurveKey, type HfColorGradingHueCurves, type HfColorGradingHueRange, type HfColorGradingSecondary, type HfColorGradingSecondaryCorrection, type HfColorGradingSoftRange, type HfColorGradingTonalWheel, type HfColorGradingWheelKey, type HfColorGradingWheels, type HfColorCurvePoint, type HfHueCurvePoint, type NormalizedHfColorGrading, type NormalizedHfColorGradingCurves, type NormalizedHfColorGradingHueCurves, type NormalizedHfColorGradingSecondary, type NormalizedHfColorGradingWheels, type ResolvedHfColorGrading, } from "./colorGrading.js";
 export { parseCubeLut, CubeLutParseError, type ParseCubeLutOptions } from "./colorLuts.js";
 export { firstFrameColourArgs, hdrToSdrToneMapFilter, parseFirstFrameColour, type ToneMapSourceColour, } from "./hdrToneMap.js";
-export { HEAVY_BITRATE, HEAVY_PIXEL_SHARE, PREVIEW_PROXY_BOX_PARAM, PREVIEW_PROXY_LIGHT_PARAM, PREVIEW_PROXY_PROGRESS_HEADER, PREVIEW_PROXY_RETRY_PARAM, PREVIEW_QUALITY_LEVELS, formatPreviewProxyBox, isHeavyForPreview, isPreviewQuality, parsePreviewProxyBox, quantizePreviewProxyBox, scalePreviewProxyBox, type PreviewProxyBox, type PreviewQuality, type PreviewSourceFacts, } from "./previewProxyBox.js";
+export { HEAVY_BITRATE, HEAVY_PIXEL_SHARE, PREVIEW_PROXY_BOX_PARAM, PREVIEW_PROXY_LIGHT_PARAM, PREVIEW_PROXY_PRIORITY_HEADER, PREVIEW_PROXY_PROGRESS_HEADER, PREVIEW_PROXY_RETRY_PARAM, PREVIEW_QUALITY_LEVELS, formatPreviewProxyBox, isHeavyForPreview, isPreviewQuality, parsePreviewProxyBox, quantizePreviewProxyBox, scalePreviewProxyBox, type PreviewProxyBox, type PreviewQuality, type PreviewSourceFacts, } from "./previewProxyBox.js";
 export { HYPERFRAME_RUNTIME_ARTIFACTS, HYPERFRAME_RUNTIME_CONTRACT, loadHyperframeRuntimeSource, type HyperframeRuntimeContract, } from "./inline-scripts/hyperframe.js";
 export { HYPERFRAME_RUNTIME_GLOBALS, HYPERFRAME_BRIDGE_SOURCES, HYPERFRAME_CONTROL_ACTIONS, type HyperframeControlAction, } from "./inline-scripts/runtimeContract.js";
 export { getHyperframeRuntimeScript } from "./generated/runtime-inline.js";

package/dist/index.js

@@ -30,7 +30,7 @@ export { clearGifFramesBeforeNext, gifClearsAfterLeavingFrameInPlace, parseAnima
 export { HF_COLOR_GRADING_ATTR, HF_COLOR_GRADING_ADJUST_KEYS, HF_COLOR_GRADING_ACTIVE_EFFECT_KEYS, HF_COLOR_GRADING_ANIMATABLE_PROPERTIES, HF_COLOR_GRADING_CANVAS_ID_PREFIX, HF_COLOR_GRADING_COLOR_SPACE, HF_COLOR_GRADING_CURVE_KEYS, HF_COLOR_GRADING_DETAIL_KEYS, HF_COLOR_GRADING_EFFECT_APPLY_DEFAULTS, HF_COLOR_GRADING_EFFECT_KEYS, HF_COLOR_GRADING_EFFECT_PRESETS, HF_COLOR_GRADING_GRADE_PRESETS, HF_COLOR_GRADING_HUE_CURVE_KEYS, HF_COLOR_GRADING_LUT_KEYS, HF_COLOR_GRADING_PALETTES, HF_COLOR_GRADING_PRESETS, HF_COLOR_GRADING_TOP_LEVEL_KEYS, HF_COLOR_GRADING_WHEEL_KEYS, getHfColorGradingCapabilities, hasHfColorGradingAuthoredValues, isHfColorGradingActive, normalizeHfColorGrading, normalizeHfColorGradingWithVariables, resolveHfColorGradingVariables, serializeHfColorGrading, } from "./colorGrading.js";
 export { parseCubeLut, CubeLutParseError } from "./colorLuts.js";
 export { firstFrameColourArgs, hdrToSdrToneMapFilter, parseFirstFrameColour, } from "./hdrToneMap.js";
-export { HEAVY_BITRATE, HEAVY_PIXEL_SHARE, PREVIEW_PROXY_BOX_PARAM, PREVIEW_PROXY_LIGHT_PARAM, PREVIEW_PROXY_PROGRESS_HEADER, PREVIEW_PROXY_RETRY_PARAM, PREVIEW_QUALITY_LEVELS, formatPreviewProxyBox, isHeavyForPreview, isPreviewQuality, parsePreviewProxyBox, quantizePreviewProxyBox, scalePreviewProxyBox, } from "./previewProxyBox.js";
+export { HEAVY_BITRATE, HEAVY_PIXEL_SHARE, PREVIEW_PROXY_BOX_PARAM, PREVIEW_PROXY_LIGHT_PARAM, PREVIEW_PROXY_PRIORITY_HEADER, PREVIEW_PROXY_PROGRESS_HEADER, PREVIEW_PROXY_RETRY_PARAM, PREVIEW_QUALITY_LEVELS, formatPreviewProxyBox, isHeavyForPreview, isPreviewQuality, parsePreviewProxyBox, quantizePreviewProxyBox, scalePreviewProxyBox, } from "./previewProxyBox.js";
 // Inline scripts
 export { HYPERFRAME_RUNTIME_ARTIFACTS, HYPERFRAME_RUNTIME_CONTRACT, loadHyperframeRuntimeSource, } from "./inline-scripts/hyperframe.js";
 export { HYPERFRAME_RUNTIME_GLOBALS, HYPERFRAME_BRIDGE_SOURCES, HYPERFRAME_CONTROL_ACTIONS, } from "./inline-scripts/runtimeContract.js";

package/dist/previewProxyBox.d.ts

@@ -3,6 +3,7 @@ export declare const PREVIEW_PROXY_BOX_PARAM = "hf-proxy-box";
 export declare const PREVIEW_PROXY_LIGHT_PARAM = "hf-proxy-light";
 export declare const PREVIEW_PROXY_RETRY_PARAM = "hf-proxy-retry";
 export declare const PREVIEW_PROXY_PROGRESS_HEADER = "X-HF-Proxy-Progress";
+export declare const PREVIEW_PROXY_PRIORITY_HEADER = "X-HF-Proxy-Priority";
 export type PreviewProxyBox = {
     width: number;
     height: number;

package/dist/previewProxyBox.js

@@ -3,6 +3,7 @@ export const PREVIEW_PROXY_BOX_PARAM = "hf-proxy-box";
 export const PREVIEW_PROXY_LIGHT_PARAM = "hf-proxy-light";
 export const PREVIEW_PROXY_RETRY_PARAM = "hf-proxy-retry";
 export const PREVIEW_PROXY_PROGRESS_HEADER = "X-HF-Proxy-Progress";
+export const PREVIEW_PROXY_PRIORITY_HEADER = "X-HF-Proxy-Priority";
 // 256 * 2^(k/4), even: nearby boxes share one cached copy, and a rung overshoots by at most ~19%.
 const RUNGS = [
     256, 304, 362, 430, 512, 608, 724, 862, 1024, 1218, 1448, 1722, 2048, 2436, 2896, 3444, 4096,

package/dist/removeScratch.d.ts

@@ -0,0 +1,5 @@
+/** Removes a scratch folder or file the mix is already done with. A refusal (Windows temp folders that deny
+ * delete) leaves it for the render's own cleanup and never fails the audio it served. */
+export declare function removeScratch(path: string): void;
+/** Runs `run`; whatever removeScratch left behind inside it (this run's only) goes to `report` once it ends. */
+export declare function collectScratchLeftovers<T>(run: () => Promise<T>, report: (left: string[]) => void): Promise<T>;

package/dist/removeScratch.js

@@ -0,0 +1,23 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { rmSync } from "node:fs";
+const collecting = new AsyncLocalStorage();
+/** Removes a scratch folder or file the mix is already done with. A refusal (Windows temp folders that deny
+ * delete) leaves it for the render's own cleanup and never fails the audio it served. */
+export function removeScratch(path) {
+    try {
+        rmSync(path, { recursive: true, force: true });
+    }
+    catch {
+        collecting.getStore()?.push(path);
+    }
+}
+/** Runs `run`; whatever removeScratch left behind inside it (this run's only) goes to `report` once it ends. */
+export async function collectScratchLeftovers(run, report) {
+    const left = [];
+    try {
+        return await collecting.run(left, run);
+    }
+    finally {
+        report(left);
+    }
+}

package/dist/renameWithRetry.d.ts

@@ -0,0 +1,16 @@
+interface Options {
+    platform?: NodeJS.Platform;
+    /** Copy the bytes when Windows keeps refusing (a TEMP that denies delete). Not atomic: scratch files only. */
+    copyFallback?: boolean;
+}
+/** `renameSync` that rides out Windows' transient file locks; other platforms and errors throw at once. */
+export declare function renameWithRetry(from: string, to: string, options?: Options & {
+    rename?: (from: string, to: string) => void;
+    copy?: (from: string, to: string) => void;
+}): void;
+/** Async twin of {@link renameWithRetry}. */
+export declare function renameWithRetryAsync(from: string, to: string, options?: Options & {
+    rename?: (from: string, to: string) => Promise<void>;
+    copy?: (from: string, to: string) => Promise<void>;
+}): Promise<void>;
+export {};

package/dist/renameWithRetry.js

@@ -0,0 +1,81 @@
+import { copyFileSync, renameSync } from "node:fs";
+import { copyFile, rename } from "node:fs/promises";
+import { removeScratch } from "./removeScratch.js";
+// Windows reports EPERM/EACCES/EBUSY while antivirus or a just-exited process still holds the
+// file; the hold clears within milliseconds. Total wait before giving up: about 1.3 s.
+const RETRYABLE = new Set(["EPERM", "EACCES", "EBUSY"]);
+const BACKOFF_MS = [10, 20, 40, 80, 160, 320, 640];
+function isRetryable(error, platform) {
+    if (platform !== "win32")
+        return false;
+    return RETRYABLE.has(error?.code ?? "");
+}
+/** What a refused rename does next: wait and try again, fall back to a copy, or give up with the error. */
+function nextStep(error, attempt, options, platform) {
+    if (!isRetryable(error, platform))
+        return "throw";
+    if (attempt < BACKOFF_MS.length)
+        return "wait";
+    return options.copyFallback ? "copy" : "throw";
+}
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/** `renameSync` that rides out Windows' transient file locks; other platforms and errors throw at once. */
+export function renameWithRetry(from, to, options = {}) {
+    const doRename = options.rename ?? renameSync;
+    const doCopy = options.copy ?? copyFileSync;
+    const platform = options.platform ?? process.platform;
+    for (let attempt = 0;; attempt++) {
+        try {
+            doRename(from, to);
+            return;
+        }
+        catch (error) {
+            const step = nextStep(error, attempt, options, platform);
+            if (step === "throw")
+                throw error;
+            if (step === "wait") {
+                sleepSync(BACKOFF_MS[attempt]);
+                continue;
+            }
+            try {
+                doCopy(from, to);
+            }
+            catch {
+                throw error;
+            }
+            removeScratch(from);
+            return;
+        }
+    }
+}
+/** Async twin of {@link renameWithRetry}. */
+export async function renameWithRetryAsync(from, to, options = {}) {
+    const doRename = options.rename ?? rename;
+    const doCopy = options.copy ?? copyFile;
+    const platform = options.platform ?? process.platform;
+    for (let attempt = 0;; attempt++) {
+        try {
+            await doRename(from, to);
+            return;
+        }
+        catch (error) {
+            const step = nextStep(error, attempt, options, platform);
+            if (step === "throw")
+                throw error;
+            if (step === "wait") {
+                await new Promise((resolve) => setTimeout(resolve, BACKOFF_MS[attempt]));
+                continue;
+            }
+            try {
+                await doCopy(from, to);
+            }
+            catch {
+                throw error;
+            }
+            removeScratch(from);
+            return;
+        }
+    }
+}

package/dist/runtime/applyVariableBindings.d.ts

@@ -21,10 +21,10 @@
  * chain the color-grading runtime uses: `__hfVariablesByComp[compId]` for
  * inlined sub-compositions, then the top-level merged `getVariables()`.
  *
- * Applied at init AND re-applied after the composition loader inlines
- * external / template sub-compositions (their DOM and per-instance scoped
- * values don't exist at init). Idempotent: re-applying writes the same
- * values.
+ * Text is bound before composition scripts run; all of it at init and after
+ * the composition loader inlines external / template sub-compositions (their
+ * DOM and per-instance scoped values don't exist at init). Idempotent:
+ * re-applying writes the same values.
  */
 /**
  * Strip characters that could smuggle additional declarations or markup out of
@@ -45,3 +45,5 @@ export declare function sanitizeCssValue(value: string): string;
 export declare function unproxiedMediaSrc(el: Element): string | null;
 /** Applies the bindings in `doc`, or only those inside `within` and `within` itself. */
 export declare function applyVariableBindings(doc: Document, within?: Element): void;
+/** Binds only text, in `doc` or inside `within`: what composition scripts read before they run. */
+export declare function applyTextBindings(doc: Document, within?: Element): void;

package/dist/runtime/applyVariableBindings.js

@@ -21,10 +21,10 @@
  * chain the color-grading runtime uses: `__hfVariablesByComp[compId]` for
  * inlined sub-compositions, then the top-level merged `getVariables()`.
  *
- * Applied at init AND re-applied after the composition loader inlines
- * external / template sub-compositions (their DOM and per-instance scoped
- * values don't exist at init). Idempotent: re-applying writes the same
- * values.
+ * Text is bound before composition scripts run; all of it at init and after
+ * the composition loader inlines external / template sub-compositions (their
+ * DOM and per-instance scoped values don't exist at init). Idempotent:
+ * re-applying writes the same values.
  */
 import { readVariablesForElement } from "./variableScope.js";
 import { isScalarVariableValue as isScalar, isSafeMediaUrl, } from "@hyperframes/parsers/composition";
@@ -154,12 +154,13 @@ function variableSrcFor(el, cache, warn = true) {
 export function unproxiedMediaSrc(el) {
     return variableSrcFor(el, new Map(), false) ?? unproxiedSrc(el);
 }
+const matching = (doc, within, selector) => within
+    ? [...(within.matches(selector) ? [within] : []), ...within.querySelectorAll(selector)]
+    : Array.from(doc.querySelectorAll(selector));
 /** Applies the bindings in `doc`, or only those inside `within` and `within` itself. */
 export function applyVariableBindings(doc, within) {
     const cache = new Map();
-    const all = (selector) => within
-        ? [...(within.matches(selector) ? [within] : []), ...within.querySelectorAll(selector)]
-        : Array.from(doc.querySelectorAll(selector));
+    const all = (selector) => matching(doc, within, selector);
     const topRoot = within ? null : findTopRoot(doc);
     applyCssCustomProperties([...(topRoot ? [topRoot] : []), ...all("[data-composition-id]")], cache);
     for (const el of all("[data-var-src]")) {
@@ -167,12 +168,23 @@ export function applyVariableBindings(doc, within) {
         if (url !== null && unproxiedSrc(el) !== url)
             el.setAttribute("src", url);
     }
-    for (const el of all("[data-var-text]")) {
+    bindText(all("[data-var-text]"), cache);
+}
+/** Binds only text, in `doc` or inside `within`: what composition scripts read before they run. */
+export function applyTextBindings(doc, within) {
+    bindText(matching(doc, within, "[data-var-text]"), new Map());
+}
+const textWrittenOnce = new WeakSet();
+/** Writes each binding once: a script may then reshape the text, which a second write would duplicate. */
+function bindText(elements, cache) {
+    for (const el of elements) {
         const id = el.getAttribute("data-var-text")?.trim();
-        if (!id)
+        if (!id || textWrittenOnce.has(el))
             continue;
         const value = valuesForElement(el, cache)[id];
-        if (isScalar(value))
-            setOwnTextPreservingChildren(el, String(value));
+        if (!isScalar(value))
+            continue;
+        setOwnTextPreservingChildren(el, String(value));
+        textWrittenOnce.add(el);
     }
 }

package/dist/runtime/getVariables.js

@@ -20,18 +20,19 @@
  *     const { title = "Untitled", theme = "light" } = getVariables<MyVars>();
  */
 import { cssVariableName, detectSlugCollisions } from "../tokenSlug.js";
+import { scopedVariablesFor } from "./variableScope.js";
 export function getVariables() {
     if (typeof document === "undefined")
         return {};
-    // Same collection the CSS-variable injection uses: <html> first, then any
-    // composition element carrying the attribute (later declarers win), then
-    // render-time overrides.
+    // <html> first, then any element carrying the attribute (later declarers win), then render-time
+    // overrides. A sub-composition's declaration is its own scope's, read from its scoped table.
     const declarers = new Set();
     if (document.documentElement?.hasAttribute("data-composition-variables")) {
         declarers.add(document.documentElement);
     }
     for (const el of Array.from(document.querySelectorAll("[data-composition-variables]"))) {
-        declarers.add(el);
+        if (!scopedVariablesFor(el))
+            declarers.add(el);
     }
     const declaredDefaults = {};
     for (const el of declarers) {

package/dist/runtime/variableScope.d.ts

@@ -5,4 +5,6 @@
  * runtime consumer of variables (color grading, declarative bindings) so the
  * scope chain can never diverge between channels.
  */
+/** The per-instance values of the inlined sub-composition an element belongs to, if any. */
+export declare function scopedVariablesFor(element: Element): Record<string, unknown> | undefined;
 export declare function readVariablesForElement(element: Element): Record<string, unknown>;

package/dist/runtime/variableScope.js

@@ -5,11 +5,17 @@
  * runtime consumer of variables (color grading, declarative bindings) so the
  * scope chain can never diverge between channels.
  */
-export function readVariablesForElement(element) {
-    const win = window;
+/** The per-instance values of the inlined sub-composition an element belongs to, if any. */
+export function scopedVariablesFor(element) {
     const scope = element.closest("[data-composition-id]");
     const compositionId = scope?.getAttribute("data-composition-id")?.trim() ?? "";
-    const scoped = compositionId ? win.__hfVariablesByComp?.[compositionId] : undefined;
+    return compositionId
+        ? window.__hfVariablesByComp?.[compositionId]
+        : undefined;
+}
+export function readVariablesForElement(element) {
+    const win = window;
+    const scoped = scopedVariablesFor(element);
     if (scoped)
         return scoped;
     const fromHelper = win.__hyperframes?.getVariables?.();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/core",
-  "version": "0.8.208",
+  "version": "0.8.210",
   "description": "",
   "repository": {
     "type": "git",
@@ -64,6 +64,14 @@
       "import": "./dist/removeTree.js",
       "types": "./dist/removeTree.d.ts"
     },
+    "./rename-retry": {
+      "import": "./dist/renameWithRetry.js",
+      "types": "./dist/renameWithRetry.d.ts"
+    },
+    "./remove-scratch": {
+      "import": "./dist/removeScratch.js",
+      "types": "./dist/removeScratch.d.ts"
+    },
     "./project-folders": {
       "import": "./dist/projectFolders.js",
       "types": "./dist/projectFolders.d.ts"
@@ -417,9 +425,9 @@
     "linkedom": "^0.18.12",
     "postcss": "^8.5.8",
     "wawoff2": "^2.0.1",
-    "@hyperframes/lint": "0.8.208",
-    "@hyperframes/studio-server": "0.8.208",
-    "@hyperframes/parsers": "0.8.208"
+    "@hyperframes/lint": "0.8.210",
+    "@hyperframes/studio-server": "0.8.210",
+    "@hyperframes/parsers": "0.8.210"
   },
   "devDependencies": {
     "@fontsource/archivo-black": "^5.2.8",