@hyperframes/core 0.8.205 → 0.8.207

package/dist/compiler/compositionScoping.d.ts

@@ -13,6 +13,8 @@ export declare function hoistFontFaceRules(styleTexts: string[]): {
     styles: string[];
     faces: string[];
 };
+export declare const AUTHORED_SOURCE_BEGIN = "/*hf-authored-begin*/";
+export declare const AUTHORED_SOURCE_END = "/*hf-authored-end*/";
 export declare function scopedModulePrelude(timelineCompositionId: string, compositionSrc?: string | null): string;
 export declare function wrapScopedCompositionScript(source: string, compositionId: string, errorLabel?: string, scopeSelectorOverride?: string, timelineCompositionId?: string, authoredRootId?: string | null, compositionSrc?: string | null): string;
 export declare function wrapInlineScriptWithErrorBoundary(source: string, errorLabel: string): string;

package/dist/compiler/compositionScoping.js

@@ -295,6 +295,8 @@ const SCOPED_HYPERFRAMES_EXPRESSION = `!__hfBaseHyperframes
           return scoped ? Object.assign({}, scoped) : {};
         },
       })`;
+export const AUTHORED_SOURCE_BEGIN = "/*hf-authored-begin*/";
+export const AUTHORED_SOURCE_END = "/*hf-authored-end*/";
 export function scopedModulePrelude(timelineCompositionId, compositionSrc) {
     return `const __hyperframes = (function(__hfBaseHyperframes, __hfTimelineCompId, __hfCompositionSrc) {
   return ${SCOPED_HYPERFRAMES_EXPRESSION};
@@ -310,6 +312,7 @@ export function wrapScopedCompositionScript(source, compositionId, errorLabel =
     const authoredRootIdLiteral = jsonScriptLiteral(authoredRootId?.trim() || null);
     const scopeSelectorLiteral = jsonScriptLiteral(scopeSelectorOverride ?? null);
     const rootSelectorPatternLiteral = jsonScriptLiteral(String.raw `\[\s*data-composition-id\s*=\s*(?:"${escapedCompositionId}"|'${escapedCompositionId}')\s*\]`);
+    const timelineRootSelectorPatternLiteral = jsonScriptLiteral(String.raw `\[\s*data-composition-id\s*=\s*(?:"${escapeRegExp(timelineCompositionId)}"|'${escapeRegExp(timelineCompositionId)}')\s*\]`);
     const timingSelectorPatternLiteral = jsonScriptLiteral(String.raw `\s*\[\s*data-(?:start|duration)\s*=\s*(?:"[^"]*"|'[^']*')\s*\]`);
     const aliasInstallerOutsideAuthoredStrictness = `(function(){ ${getSvgSelectorAliasesScript()} })();`;
     return `(function(){
@@ -328,6 +331,7 @@ export function wrapScopedCompositionScript(source, compositionId, errorLabel =
     : "");
   var __hfRoot = null;
   var __hfRootSelectorPattern = ${rootSelectorPatternLiteral};
+  var __hfTimelineRootSelectorPattern = ${timelineRootSelectorPatternLiteral};
   var __hfTimingSelectorPattern = ${timingSelectorPatternLiteral};
   var __hfAuthoredRootSelector = __hfAuthoredRootId
     ? "[" + __hfAuthoredRootAttr + '="' + __hfEscapeAttr(__hfAuthoredRootId) + '"]'
@@ -339,7 +343,11 @@ export function wrapScopedCompositionScript(source, compositionId, errorLabel =
     if (!__hfCompId || typeof selector !== "string") return selector;
     var normalized = selector
       .replace(new RegExp(__hfRootSelectorPattern + '(?:' + __hfTimingSelectorPattern + ')+', 'g'), __hfRootSelector)
-      .replace(new RegExp('(?:' + __hfTimingSelectorPattern + ')+' + __hfRootSelectorPattern, 'g'), __hfRootSelector);
+      .replace(new RegExp('(?:' + __hfTimingSelectorPattern + ')+' + __hfRootSelectorPattern, 'g'), __hfRootSelector)
+      .replace(new RegExp(__hfRootSelectorPattern, 'g'), __hfRootSelector);
+    if (__hfTimelineCompId !== __hfCompId) {
+      normalized = normalized.replace(new RegExp(__hfTimelineRootSelectorPattern, 'g'), __hfRootSelector);
+    }
     return window.__hfSvgSelectorAliases.rewrite(normalized, __hfAuthoredRootEntries);
   };
   var __hfFindRoot = function() {
@@ -581,7 +589,9 @@ export function wrapScopedCompositionScript(source, compositionId, errorLabel =
     if (typeof report === "function") report("start", __hfCompositionSrc || "index.html");
     try {
       (function(document, gsap, window, __hyperframes) {
+${AUTHORED_SOURCE_BEGIN}
 ${source.replace(/<\/(script)/gi, "<\\/$1")}
+${AUTHORED_SOURCE_END}
       }).call(window, __hfScopedDocument, __hfScopedGsap, __hfScopedWindow, __hfScopedHyperframes);
     } catch (_err) {
       console.error(__hfErrorLabel, __hfCompId, _err);

package/dist/compiler/htmlBundler.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { compositionStyle, cssStyleMergeKey, deferScriptsUntilFonts, isAlwaysAppliedStyle, headStyleRuns, INLINED_FILE_ATTR, inlineScriptRuns, styleElementsFor, } from "./scriptRuns.js";
 import { countPageRoot, executableScripts, isJavaScriptType, planCompositionAssembly, } from "./compositionAssembly.js";
 import { SCENE_FONTS_ATTR, SCENE_PART_ATTR } from "../sceneParts.js";
+import { stripSdrPngColourTags } from "./pngColourTags.js";
 import { ensureExternalScriptTag, readExternalScriptAttributes, } from "./externalScripts.js";
 import { emitMountedModuleScripts, parseImportMap } from "./importMaps.js";
 import { markFlattenedInnerRoot } from "../runtime/flattenedRoot.js";
@@ -313,7 +314,8 @@ function createAssetInliner(resolveProjectPath, inlineAssets) {
         const byteLength = safeStatSize(filePath);
         if (byteLength !== null && byteLength > MAX_INLINE_ASSET_BYTES)
             return { tooLarge: byteLength };
-        const content = safeReadFileBuffer(filePath);
+        const read = safeReadFileBuffer(filePath);
+        const content = read && mimeType === "image/png" ? (stripSdrPngColourTags(read) ?? read) : read;
         return {
             dataUrl: content === null ? null : `data:${mimeType};base64,${content.toString("base64")}`,
         };

package/dist/compiler/inlineSubCompositions.js

@@ -13,7 +13,7 @@ import { compositionStyle, cssStyleMergeKey, hasSameLink, } from "./scriptRuns.j
  */
 import { rewriteAssetPath, rewriteAssetPaths, rewriteCssAssetUrls, rewriteInlineStyleAssetUrls, } from "./rewriteSubCompPaths.js";
 import { warnUnknownEnumValues } from "../runtime/getVariables.js";
-import { createCompositionCssScoper, wrapInlineScriptWithErrorBoundary, scopedModulePrelude, wrapScopedCompositionScript, } from "./compositionScoping.js";
+import { createCompositionCssScoper, AUTHORED_SOURCE_BEGIN, AUTHORED_SOURCE_END, wrapInlineScriptWithErrorBoundary, scopedModulePrelude, wrapScopedCompositionScript, } from "./compositionScoping.js";
 import { namespaceCollidingSvgIds, rewriteSvgIdReferencesInCss, } from "./svgIdNamespacing.js";
 import { checkSubCompositionUsability, resolveSubCompositionContent, } from "@hyperframes/parsers/sub-composition-validity";
 import { enumerateNestedCompositionHosts, planCompositionAssembly, extractedCompositionAssets, } from "./compositionAssembly.js";
@@ -419,7 +419,7 @@ export function inlineSubCompositions(document, hosts, options) {
                 const prelude = scriptCompositionId
                     ? scopedModulePrelude(runtimeCompId || scopeCompId || scriptCompositionId, src)
                     : "";
-                moduleScripts.push(prelude + (scriptEl.textContent || ""));
+                moduleScripts.push(`${prelude}${AUTHORED_SOURCE_BEGIN}\n${scriptEl.textContent || ""}\n${AUTHORED_SOURCE_END}`);
             }
             else if (externalSrc) {
                 if (!externalScriptSrcs.includes(externalSrc)) {

package/dist/compiler/pngColourTags.d.ts

@@ -0,0 +1,2 @@
+/** An SDR PNG's copy without the tags that make Chrome re-map its pixels; null if none apply or it is HDR. */
+export declare function stripSdrPngColourTags(png: Uint8Array): Buffer | null;

package/dist/compiler/pngColourTags.js

@@ -0,0 +1,27 @@
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const PNG_SIGNATURE_BYTES = PNG_SIGNATURE.length;
+const CHUNK_OVERHEAD_BYTES = 12;
+const REMOVED_CHUNKS = new Set(["cICP", "gAMA", "cHRM"]);
+const HDR_CICP_TRANSFERS = new Set([16, 18]);
+/** An SDR PNG's copy without the tags that make Chrome re-map its pixels; null if none apply or it is HDR. */
+export function stripSdrPngColourTags(png) {
+    const bytes = Buffer.from(png.buffer, png.byteOffset, png.byteLength);
+    if (!bytes.subarray(0, PNG_SIGNATURE_BYTES).equals(PNG_SIGNATURE))
+        return null;
+    const kept = [bytes.subarray(0, PNG_SIGNATURE_BYTES)];
+    let removed = false;
+    for (let at = PNG_SIGNATURE_BYTES; at + CHUNK_OVERHEAD_BYTES <= bytes.length;) {
+        const end = at + CHUNK_OVERHEAD_BYTES + bytes.readUInt32BE(at);
+        if (end > bytes.length)
+            return null;
+        const type = bytes.toString("latin1", at + 4, at + 8);
+        if (type === "cICP" && HDR_CICP_TRANSFERS.has(bytes[at + 9] ?? 0))
+            return null;
+        if (REMOVED_CHUNKS.has(type))
+            removed = true;
+        else
+            kept.push(bytes.subarray(at, end));
+        at = end;
+    }
+    return removed ? Buffer.concat(kept) : null;
+}

package/dist/compiler/selectorIdTokens.d.ts

@@ -62,7 +62,7 @@ export declare function parseAttributeSelector(predicate: string): {
     name: string;
     rawName: string;
     namespace: AttributeNamespace;
-    operator: "=" | "~=" | "|=" | "^=" | "$=" | "*=";
+    operator: "=" | "*=" | "|=" | "^=" | "~=" | "$=";
     value: string;
     flag: string | undefined;
 } | null;

package/dist/core.types.d.ts

@@ -1,70 +1,6 @@
 export type ExecutionMode = "planning" | "design" | "execution" | null;
-/**
- * Frame rate as an exact rational. Carrying `{num, den}` end-to-end (rather
- * than collapsing to `29.97`) lets us pass NTSC / drop-frame rates straight
- * through to FFmpeg via `-r 30000/1001` without any decimal round-trip.
- *
- * Integer fps is represented with `den: 1` (e.g. `{ num: 30, den: 1 }`).
- *
- * Use {@link fpsToNumber} when arithmetic forces a decimal (e.g. `setTimeout`
- * intervals) and {@link fpsToFfmpegArg} when emitting FFmpeg `-r` /
- * `-framerate` strings.
- */
-export interface Fps {
-    num: number;
-    den: number;
-}
-export type FpsInput = number | Fps;
-export declare function toFps(input: FpsInput): Fps;
-/**
- * Decimal value of an {@link Fps} rational. Used at sites that need a
- * `number` for arithmetic (frame-index → time, frame intervals, telemetry
- * payloads) where the small precision loss of the decimal is acceptable.
- */
-export declare function fpsToNumber(fps: Fps): number;
-/**
- * FFmpeg-style fps argument. Returns `"30"` for integer fps and `"30000/1001"`
- * for rationals — both forms are accepted verbatim by FFmpeg's `-r` and
- * `-framerate` flags. We keep integer fps as a bare integer so existing
- * snapshot tests / log output don't churn for the common case.
- */
-export declare function fpsToFfmpegArg(fps: Fps): string;
-/**
- * Discriminated parse result for {@link parseFps}. Lets the CLI / route
- * validation own its own error UX without losing the structured failure
- * reason.
- */
-export type FpsParseResult = {
-    ok: true;
-    value: Fps;
-} | {
-    ok: false;
-    reason: "empty" | "not-a-number" | "non-positive" | "out-of-range" | "invalid-fraction" | "ambiguous-decimal";
-};
-/**
- * Parse a user-supplied fps spec into an {@link Fps} rational.
- *
- * Accepted forms:
- * - integer string `"30"` → `{ num: 30, den: 1 }`
- * - integer number `30` → `{ num: 30, den: 1 }`
- * - rational string `"30000/1001"` → `{ num: 30000, den: 1001 }` (exact NTSC)
- *
- * Rejected:
- * - empty / non-numeric input
- * - decimals like `"29.97"` — callers must spell rationals with `/` so the
- *   exact denominator is unambiguous (FFmpeg treats `29.97` as a slightly
- *   different framerate than `30000/1001`).
- * - division by zero, negative or zero numerator
- * - decimal value outside `[1, 240]` — defensive bounds for "human" fps
- *   ranges (24, 25, 30, 50, 60, 120, 240, plus the NTSC trio).
- */
-export declare function parseFps(input: string | number): FpsParseResult;
-/**
- * Convenience wrapper around {@link parseFps} for callsites that want the
- * default-30-fps fallback when input is `undefined`. Does NOT swallow parse
- * errors — those still surface via the discriminated result.
- */
-export declare function parseFpsWithDefault(input: string | number | undefined): FpsParseResult;
+export type { Fps, FpsInput, FpsParseResult } from "./fps.js";
+export { toFps, fpsToNumber, fpsToFfmpegArg, parseFps, parseFpsWithDefault } from "./fps.js";
 /** Video orientation / aspect ratio. */
 export type Orientation = "16:9" | "9:16";
 export type { Asset, TimelineElementType, MediaElementType, TimelineElementBase, TimelineMediaElement, WaveformData, TimelineTextElement, TimelineCompositionElement, CompositionVariableType, CompositionVariableBase, StringVariable, NumberVariable, ColorVariable, BooleanVariable, EnumVariable, CompositionVariable, CompositionSpec, TimelineElement, MediaFile, CanvasResolution, CompositionAPI, PlayerAPI, AddElementData, ValidationResult, CompositionAsset, Keyframe, KeyframeProperties, ElementKeyframes, StageZoom, StageZoomKeyframe, } from "@hyperframes/parsers";

package/dist/core.types.js

@@ -1,104 +1,3 @@
 // ── Shared cross-package types ──────────────────────────────────────────────
-export function toFps(input) {
-    if (typeof input === "number") {
-        return { num: input, den: 1 };
-    }
-    return input;
-}
-/**
- * Decimal value of an {@link Fps} rational. Used at sites that need a
- * `number` for arithmetic (frame-index → time, frame intervals, telemetry
- * payloads) where the small precision loss of the decimal is acceptable.
- */
-export function fpsToNumber(fps) {
-    return fps.num / fps.den;
-}
-/**
- * FFmpeg-style fps argument. Returns `"30"` for integer fps and `"30000/1001"`
- * for rationals — both forms are accepted verbatim by FFmpeg's `-r` and
- * `-framerate` flags. We keep integer fps as a bare integer so existing
- * snapshot tests / log output don't churn for the common case.
- */
-export function fpsToFfmpegArg(fps) {
-    return fps.den === 1 ? String(fps.num) : `${fps.num}/${fps.den}`;
-}
-/**
- * Parse a user-supplied fps spec into an {@link Fps} rational.
- *
- * Accepted forms:
- * - integer string `"30"` → `{ num: 30, den: 1 }`
- * - integer number `30` → `{ num: 30, den: 1 }`
- * - rational string `"30000/1001"` → `{ num: 30000, den: 1001 }` (exact NTSC)
- *
- * Rejected:
- * - empty / non-numeric input
- * - decimals like `"29.97"` — callers must spell rationals with `/` so the
- *   exact denominator is unambiguous (FFmpeg treats `29.97` as a slightly
- *   different framerate than `30000/1001`).
- * - division by zero, negative or zero numerator
- * - decimal value outside `[1, 240]` — defensive bounds for "human" fps
- *   ranges (24, 25, 30, 50, 60, 120, 240, plus the NTSC trio).
- */
-export function parseFps(input) {
-    if (typeof input === "number") {
-        if (!Number.isFinite(input))
-            return { ok: false, reason: "not-a-number" };
-        if (!Number.isInteger(input))
-            return { ok: false, reason: "ambiguous-decimal" };
-        if (input <= 0)
-            return { ok: false, reason: "non-positive" };
-        if (input > 240)
-            return { ok: false, reason: "out-of-range" };
-        return { ok: true, value: { num: input, den: 1 } };
-    }
-    const raw = input.trim();
-    if (raw === "")
-        return { ok: false, reason: "empty" };
-    if (raw.includes("/")) {
-        const parts = raw.split("/");
-        if (parts.length !== 2)
-            return { ok: false, reason: "invalid-fraction" };
-        const num = Number(parts[0]);
-        const den = Number(parts[1]);
-        if (!Number.isFinite(num) || !Number.isFinite(den)) {
-            return { ok: false, reason: "not-a-number" };
-        }
-        if (!Number.isInteger(num) || !Number.isInteger(den)) {
-            return { ok: false, reason: "invalid-fraction" };
-        }
-        if (den <= 0)
-            return { ok: false, reason: "invalid-fraction" };
-        if (num <= 0)
-            return { ok: false, reason: "non-positive" };
-        const decimal = num / den;
-        if (decimal < 1 || decimal > 240)
-            return { ok: false, reason: "out-of-range" };
-        return { ok: true, value: { num, den } };
-    }
-    // Integer-only path — reject `"29.97"` so users are explicit about the
-    // exact rational they want.
-    if (!/^-?\d+$/.test(raw)) {
-        // Allow caller to differentiate "29.97" from "abc" if they want; both
-        // are user errors but the message can be friendlier for decimals.
-        if (/^-?\d*\.\d+$/.test(raw))
-            return { ok: false, reason: "ambiguous-decimal" };
-        return { ok: false, reason: "not-a-number" };
-    }
-    const n = Number(raw);
-    if (n <= 0)
-        return { ok: false, reason: "non-positive" };
-    if (n > 240)
-        return { ok: false, reason: "out-of-range" };
-    return { ok: true, value: { num: n, den: 1 } };
-}
-/**
- * Convenience wrapper around {@link parseFps} for callsites that want the
- * default-30-fps fallback when input is `undefined`. Does NOT swallow parse
- * errors — those still surface via the discriminated result.
- */
-export function parseFpsWithDefault(input) {
-    if (input === undefined || input === "")
-        return { ok: true, value: { num: 30, den: 1 } };
-    return parseFps(input);
-}
+export { toFps, fpsToNumber, fpsToFfmpegArg, parseFps, parseFpsWithDefault } from "./fps.js";
 export { CANVAS_DIMENSIONS, VALID_CANVAS_RESOLUTIONS, normalizeResolutionFlag, isAspectAgnosticResolutionAlias, resolveResolutionFlagPair, checkOutputResolutionCompatibility, outputResolutionForSize, suggestMatchingPreset, COMPOSITION_VARIABLE_TYPES, TIMELINE_COLORS, DEFAULT_DURATIONS, getDefaultStageZoom, isTextElement, isMediaElement, isCompositionElement, } from "@hyperframes/parsers";

package/dist/fps.d.ts

@@ -0,0 +1,17 @@
+export interface Fps {
+    num: number;
+    den: number;
+}
+export type FpsInput = number | Fps;
+export declare function toFps(input: FpsInput): Fps;
+export declare function fpsToNumber(fps: Fps): number;
+export declare function fpsToFfmpegArg(fps: Fps): string;
+export type FpsParseResult = {
+    ok: true;
+    value: Fps;
+} | {
+    ok: false;
+    reason: "empty" | "not-a-number" | "non-positive" | "out-of-range" | "invalid-fraction" | "ambiguous-decimal";
+};
+export declare function parseFps(input: string | number): FpsParseResult;
+export declare function parseFpsWithDefault(input: string | number | undefined): FpsParseResult;

package/dist/fps.js

@@ -0,0 +1,58 @@
+export function toFps(input) {
+    if (typeof input === "number") {
+        return { num: input, den: 1 };
+    }
+    return input;
+}
+export function fpsToNumber(fps) {
+    return fps.num / fps.den;
+}
+export function fpsToFfmpegArg(fps) {
+    return fps.den === 1 ? String(fps.num) : `${fps.num}/${fps.den}`;
+}
+const fail = (reason) => ({ ok: false, reason });
+function rangedFps(num, den) {
+    if (num <= 0)
+        return fail("non-positive");
+    const decimal = num / den;
+    if (decimal < 1 || decimal > 240)
+        return fail("out-of-range");
+    return { ok: true, value: { num, den } };
+}
+function numericFps(input) {
+    if (!Number.isFinite(input))
+        return fail("not-a-number");
+    if (!Number.isInteger(input))
+        return fail("ambiguous-decimal");
+    return rangedFps(input, 1);
+}
+function fractionFps(raw) {
+    const parts = raw.split("/");
+    if (parts.length !== 2)
+        return fail("invalid-fraction");
+    const num = Number(parts[0]);
+    const den = Number(parts[1]);
+    if (!Number.isFinite(num) || !Number.isFinite(den))
+        return fail("not-a-number");
+    if (!Number.isInteger(num) || !Number.isInteger(den) || den <= 0)
+        return fail("invalid-fraction");
+    return rangedFps(num, den);
+}
+// Decimals like "29.97" are rejected: FFmpeg reads them as a different rate than 30000/1001.
+export function parseFps(input) {
+    if (typeof input === "number")
+        return numericFps(input);
+    const raw = input.trim();
+    if (raw === "")
+        return fail("empty");
+    if (raw.includes("/"))
+        return fractionFps(raw);
+    if (/^-?\d+$/.test(raw))
+        return rangedFps(Number(raw), 1);
+    return fail(/^-?\d*\.\d+$/.test(raw) ? "ambiguous-decimal" : "not-a-number");
+}
+export function parseFpsWithDefault(input) {
+    if (input === undefined || input === "")
+        return { ok: true, value: { num: 30, den: 1 } };
+    return parseFps(input);
+}