@hyperframes/core 0.8.208 → 0.8.209

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.209",
   "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.209",
+    "@hyperframes/parsers": "0.8.209",
+    "@hyperframes/studio-server": "0.8.209"
   },
   "devDependencies": {
     "@fontsource/archivo-black": "^5.2.8",