hyperframes 0.6.63 → 0.6.65

package/dist/cli.js

@@ -50,7 +50,7 @@ var VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    VERSION = true ? "0.6.63" : "0.0.0-dev";
+    VERSION = true ? "0.6.65" : "0.0.0-dev";
   }
 });
 
@@ -36438,6 +36438,19 @@ function extractCompositionIdsFromCss(css) {
   }
   return [...ids];
 }
+function extractTimelineRegistryKeys(source) {
+  const keys2 = /* @__PURE__ */ new Set();
+  let match;
+  const pattern = new RegExp(
+    TIMELINE_REGISTRY_KEY_PATTERN.source,
+    TIMELINE_REGISTRY_KEY_PATTERN.flags
+  );
+  while ((match = pattern.exec(source)) !== null) {
+    const key2 = match[1] ?? match[2];
+    if (key2) keys2.add(key2);
+  }
+  return [...keys2];
+}
 function getInlineScriptSyntaxError(source) {
   if (!source.trim()) return null;
   try {
@@ -36457,7 +36470,7 @@ function truncateSnippet(value, maxLength = 220) {
   if (normalized.length <= maxLength) return normalized;
   return `${normalized.slice(0, maxLength - 3)}...`;
 }
-var TAG_PATTERN, STYLE_BLOCK_PATTERN, SCRIPT_BLOCK_PATTERN, COMPOSITION_ID_IN_CSS_PATTERN, TIMELINE_REGISTRY_INIT_PATTERN, TIMELINE_REGISTRY_ASSIGN_PATTERN, WINDOW_TIMELINE_ASSIGN_PATTERN, INVALID_SCRIPT_CLOSE_PATTERN;
+var TAG_PATTERN, STYLE_BLOCK_PATTERN, SCRIPT_BLOCK_PATTERN, COMPOSITION_ID_IN_CSS_PATTERN, TIMELINE_REGISTRY_INIT_PATTERN, TIMELINE_REGISTRY_ASSIGN_PATTERN, WINDOW_TIMELINE_ASSIGN_PATTERN, INVALID_SCRIPT_CLOSE_PATTERN, TIMELINE_REGISTRY_KEY_PATTERN;
 var init_utils2 = __esm({
   "../core/src/lint/utils.ts"() {
     "use strict";
@@ -36466,9 +36479,10 @@ var init_utils2 = __esm({
     SCRIPT_BLOCK_PATTERN = /<script\b([^>]*)>([\s\S]*?)<\/script>/gi;
     COMPOSITION_ID_IN_CSS_PATTERN = /\[data-composition-id=["']([^"']+)["']\]/g;
     TIMELINE_REGISTRY_INIT_PATTERN = /window\.__timelines\s*=\s*window\.__timelines\s*\|\|\s*\{\}|window\.__timelines\s*=\s*\{\}|window\.__timelines\s*\?\?=\s*\{\}/i;
-    TIMELINE_REGISTRY_ASSIGN_PATTERN = /window\.__timelines\[[^\]]+\]\s*=/i;
-    WINDOW_TIMELINE_ASSIGN_PATTERN = /window\.__timelines\[\s*["']([^"']+)["']\s*\]\s*=\s*([A-Za-z_$][\w$]*)/i;
+    TIMELINE_REGISTRY_ASSIGN_PATTERN = /window\.__timelines(?:\[[^\]]+\]|\.[A-Za-z_$][\w$]*)\s*=/i;
+    WINDOW_TIMELINE_ASSIGN_PATTERN = /window\.__timelines(?:\[\s*["']([^"']+)["']\s*\]|\.\s*([A-Za-z_$][\w$]*))\s*=\s*([A-Za-z_$][\w$]*)/i;
     INVALID_SCRIPT_CLOSE_PATTERN = /<script[^>]*>[\s\S]*?<\s*\/\s*script(?!>)/i;
+    TIMELINE_REGISTRY_KEY_PATTERN = /window\.__timelines(?:\[\s*["']([^"']+)["']\s*\]|\.\s*([A-Za-z_$][\w$]*))\s*=/g;
   }
 });
 
@@ -36604,13 +36618,12 @@ var init_core = __esm({
         const htmlCompIds = /* @__PURE__ */ new Set();
         const timelineRegKeys = /* @__PURE__ */ new Set();
         const compIdRe = /data-composition-id\s*=\s*["']([^"']+)["']/gi;
-        const tlKeyRe = /window\.__timelines\[\s*["']([^"']+)["']\s*\]/g;
         let m2;
         while ((m2 = compIdRe.exec(source)) !== null) {
           if (m2[1]) htmlCompIds.add(m2[1]);
         }
-        while ((m2 = tlKeyRe.exec(source)) !== null) {
-          if (m2[1]) timelineRegKeys.add(m2[1]);
+        for (const key2 of extractTimelineRegistryKeys(source)) {
+          timelineRegKeys.add(key2);
         }
         for (const key2 of timelineRegKeys) {
           if (!htmlCompIds.has(key2)) {
@@ -37358,7 +37371,7 @@ function countClassUsage(tags) {
 }
 function readRegisteredTimelineCompositionId(script) {
   const match = script.match(WINDOW_TIMELINE_ASSIGN_PATTERN);
-  return match?.[1] || null;
+  return match?.[1] || match?.[2] || null;
 }
 function unwrapRaw(value) {
   if (typeof value === "number") return value;
@@ -67373,9 +67386,9 @@ async function mixAudioTracks(tracks, outputPath, totalDuration, signal, config)
       );
     });
     const mixInputs = tracks.map((_, i2) => `[a${i2}]`).join("");
-    const weights = tracks.map(() => "1").join(" ");
-    const mixFilter = `${mixInputs}amix=inputs=${tracks.length}:duration=longest:dropout_transition=0:normalize=0:weights='${weights}'[mixed]`;
-    const postMixGainFilter = `[mixed]volume=${masterOutputGain}[out]`;
+    const mixFilter = `${mixInputs}amix=inputs=${tracks.length}:duration=longest:dropout_transition=0[mixed]`;
+    const compensatedGain = masterOutputGain * tracks.length;
+    const postMixGainFilter = `[mixed]volume=${formatFilterNumber(compensatedGain)}[out]`;
     const fullFilter = [...filterParts, mixFilter, postMixGainFilter].join(";");
     return [
       ...inputs,
@@ -71420,7 +71433,7 @@ var init_urlDownloader2 = __esm({
 
 // ../producer/src/services/htmlCompiler.ts
 import { readFileSync as readFileSync27, existsSync as existsSync35, mkdirSync as mkdirSync20 } from "fs";
-import { join as join39, dirname as dirname13, resolve as resolve19 } from "path";
+import { join as join39, dirname as dirname13, resolve as resolve19, basename as basename5 } from "path";
 function dedupeElementsById(elements) {
   const deduped = /* @__PURE__ */ new Map();
   for (const element of elements) {
@@ -71552,6 +71565,8 @@ async function compileHtmlFile(html, baseDir, downloadDir) {
     compiledHtml = clampDurations(compiledHtml, clampList);
   }
   compiledHtml = compiledHtml.replace(/(<video\b[^>]*)\s+crossorigin(?:=["'][^"']*["'])?/gi, "$1");
+  compiledHtml = compiledHtml.replace(/(<img\b[^>]*)\s+crossorigin(?:=["'][^"']*["'])?/gi, "$1");
+  compiledHtml = compiledHtml.replace(/(<audio\b[^>]*)\s+crossorigin(?:=["'][^"']*["'])?/gi, "$1");
   return { html: compiledHtml, unresolvedCompositions };
 }
 async function parseSubCompositions(html, projectDir, downloadDir, parentOffset = 0, parentEnd = Infinity, visited = /* @__PURE__ */ new Set()) {
@@ -71964,6 +71979,46 @@ function collectExternalAssets(html, projectDir) {
     externalAssets
   };
 }
+async function localizeRemoteMediaSources(html, downloadDir) {
+  const remoteDir = join39(downloadDir, REMOTE_MEDIA_SUBDIR);
+  const urlSet = /* @__PURE__ */ new Set();
+  const re2 = new RegExp(REMOTE_MEDIA_TAG_RE.source, REMOTE_MEDIA_TAG_RE.flags);
+  let m2;
+  while ((m2 = re2.exec(html)) !== null) {
+    if (m2[1]) urlSet.add(m2[1]);
+  }
+  if (urlSet.size === 0) return { html, remoteMediaAssets: /* @__PURE__ */ new Map() };
+  if (!existsSync35(remoteDir)) mkdirSync20(remoteDir, { recursive: true });
+  const urlToLocal = /* @__PURE__ */ new Map();
+  await Promise.all(
+    [...urlSet].map(async (url) => {
+      try {
+        const localPath = await downloadToTemp(url, remoteDir);
+        urlToLocal.set(url, localPath);
+      } catch (err) {
+        console.warn(
+          `[Compiler] Remote media download failed for ${url} \u2014 using original URL as fallback. ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    })
+  );
+  if (urlToLocal.size === 0) return { html, remoteMediaAssets: /* @__PURE__ */ new Map() };
+  const remoteMediaAssets = /* @__PURE__ */ new Map();
+  const urlToRelPath = /* @__PURE__ */ new Map();
+  for (const [url, absPath] of urlToLocal) {
+    const relPath = `${REMOTE_MEDIA_SUBDIR}/${basename5(absPath)}`;
+    remoteMediaAssets.set(relPath, absPath);
+    urlToRelPath.set(url, relPath);
+  }
+  let result = html;
+  for (const [url, relPath] of urlToRelPath) {
+    result = result.replaceAll(`"${url}"`, `"${relPath}"`).replaceAll(`'${url}'`, `'${relPath}'`);
+  }
+  console.log(
+    `[Compiler] Localized ${urlToLocal.size} remote media source(s) to ${REMOTE_MEDIA_SUBDIR}/`
+  );
+  return { html: result, remoteMediaAssets };
+}
 function rewriteUnresolvableGsapToCdn(html, projectDir) {
   return html.replace(
     /(<script\b[^>]*\bsrc=["'])([^"']*gsap[^"']*\/dist\/([^"']+))(["'][^>]*>)/gi,
@@ -72014,10 +72069,17 @@ async function compileForRender(projectDir, htmlPath, downloadDir, options = {})
     'data-hf-studio-motion="'
   ];
   const hasPositionEdits = HF_POSITION_ATTRS.some((attr) => htmlWithAssets.includes(attr));
-  const html = hasPositionEdits ? htmlWithAssets.replace(
+  const htmlWithPositionScript = hasPositionEdits ? htmlWithAssets.replace(
     /<\/body>/i,
     `<script>${createStudioPositionSeekReapplyScript()}</script></body>`
   ) : htmlWithAssets;
+  const { html, remoteMediaAssets } = await localizeRemoteMediaSources(
+    htmlWithPositionScript,
+    downloadDir
+  );
+  for (const [relPath, absPath] of remoteMediaAssets) {
+    externalAssets.set(relPath, absPath);
+  }
   const mainVideos = parseVideoElements(html);
   const mainAudios = parseAudioElements(html);
   const mainImages = parseImageElements(html);
@@ -72298,7 +72360,7 @@ async function recompileWithResolutions(compiled, resolutions, projectDir, downl
     hasShaderTransitions: compiled.hasShaderTransitions
   };
 }
-var INLINE_SCRIPT_PATTERN, COMPILER_MOUNT_BLOCK_START, COMPILER_MOUNT_BLOCK_END, SHADER_TRANSITION_USAGE_PATTERN, GSAP_CDN_BASE;
+var INLINE_SCRIPT_PATTERN, COMPILER_MOUNT_BLOCK_START, COMPILER_MOUNT_BLOCK_END, SHADER_TRANSITION_USAGE_PATTERN, REMOTE_MEDIA_SUBDIR, REMOTE_MEDIA_TAG_RE, GSAP_CDN_BASE;
 var init_htmlCompiler2 = __esm({
   "../producer/src/services/htmlCompiler.ts"() {
     "use strict";
@@ -72315,6 +72377,8 @@ var init_htmlCompiler2 = __esm({
     COMPILER_MOUNT_BLOCK_START = "/* __HF_COMPILER_MOUNT_START__ */";
     COMPILER_MOUNT_BLOCK_END = "/* __HF_COMPILER_MOUNT_END__ */";
     SHADER_TRANSITION_USAGE_PATTERN = /\b(?:(?:window|globalThis)\s*\.\s*)?HyperShader\s*\.\s*init\s*\(|\b__hf\s*\.\s*transitions\s*=/;
+    REMOTE_MEDIA_SUBDIR = "_remote_media";
+    REMOTE_MEDIA_TAG_RE = /<(?:video|audio)\b[^>]*?\bsrc\s*=\s*["'](https?:\/\/[^"']+)["'][^>]*>/gi;
     GSAP_CDN_BASE = "https://cdn.jsdelivr.net/npm/gsap@3.15.0/dist/";
   }
 });
@@ -78329,7 +78393,7 @@ __export(studioServer_exports, {
 import { Hono as Hono5 } from "hono";
 import { streamSSE as streamSSE3 } from "hono/streaming";
 import { existsSync as existsSync48, readFileSync as readFileSync35, writeFileSync as writeFileSync25, statSync as statSync17 } from "fs";
-import { resolve as resolve24, join as join58, basename as basename5 } from "path";
+import { resolve as resolve24, join as join58, basename as basename6 } from "path";
 function resolveDistDir() {
   return resolveStudioBundle().dir;
 }
@@ -78456,7 +78520,7 @@ async function loadPreviewServerBuildSignature() {
 }
 function createStudioServer(options) {
   const { projectDir, projectName } = options;
-  const projectId = projectName || basename5(projectDir);
+  const projectId = projectName || basename6(projectDir);
   const studioDir = resolveDistDir();
   const runtimePath = resolveRuntimePath();
   const watcher = createProjectWatcher(projectDir);
@@ -78632,19 +78696,19 @@ function createStudioServer(options) {
     async installRegistryBlock(opts) {
       const { resolveItem: resolveItem2 } = await Promise.resolve().then(() => (init_resolver(), resolver_exports));
       const { installItem: installItem2 } = await Promise.resolve().then(() => (init_installer(), installer_exports));
-      const { readFileSync: readFileSync58, writeFileSync: writeFileSync40, existsSync: existsSync81 } = await import("fs");
+      const { readFileSync: readFileSync59, writeFileSync: writeFileSync40, existsSync: existsSync81 } = await import("fs");
       const { join: join92 } = await import("path");
       const item = await resolveItem2(opts.blockName);
       const { written } = await installItem2(item, { destDir: opts.project.dir });
       const indexPath = join92(opts.project.dir, "index.html");
       if (existsSync81(indexPath)) {
-        const indexHtml = readFileSync58(indexPath, "utf-8");
+        const indexHtml = readFileSync59(indexPath, "utf-8");
         const hostW = indexHtml.match(/data-width="(\d+)"/)?.[1];
         const hostH = indexHtml.match(/data-height="(\d+)"/)?.[1];
         if (hostW && hostH) {
           for (const absPath of written) {
             if (!absPath.endsWith(".html")) continue;
-            let content = readFileSync58(absPath, "utf-8");
+            let content = readFileSync59(absPath, "utf-8");
             content = content.replace(
               /(<meta\s+name="viewport"\s+content="width=)\d+(,\s*height=)\d+/i,
               `$1${hostW}$2${hostH}`
@@ -78842,14 +78906,14 @@ __export(preview_exports, {
 });
 import { spawn as spawn11 } from "child_process";
 import { existsSync as existsSync49, lstatSync as lstatSync2, symlinkSync as symlinkSync2, unlinkSync as unlinkSync5, readlinkSync, mkdirSync as mkdirSync30 } from "fs";
-import { resolve as resolve25, dirname as dirname19, basename as basename6, join as join59 } from "path";
+import { resolve as resolve25, dirname as dirname19, basename as basename7, join as join59 } from "path";
 import { fileURLToPath as fileURLToPath6 } from "url";
 import { createRequire as createRequire2 } from "module";
 async function runDevMode(dir, options) {
   const thisFile = fileURLToPath6(import.meta.url);
   const repoRoot2 = resolve25(dirname19(thisFile), "..", "..", "..", "..");
   const projectsDir = join59(repoRoot2, "packages", "studio", "data", "projects");
-  const pName = options?.projectName ?? basename6(dir);
+  const pName = options?.projectName ?? basename7(dir);
   const symlinkPath = join59(projectsDir, pName);
   mkdirSync30(projectsDir, { recursive: true });
   let createdSymlink = false;
@@ -78939,7 +79003,7 @@ function hasLocalStudio(dir) {
 async function runLocalStudioMode(dir, options) {
   const req = createRequire2(join59(dir, "package.json"));
   const studioPkgPath = dirname19(req.resolve("@hyperframes/studio/package.json"));
-  const pName = options?.projectName ?? basename6(dir);
+  const pName = options?.projectName ?? basename7(dir);
   const projectsDir = join59(studioPkgPath, "data", "projects");
   const symlinkPath = join59(projectsDir, pName);
   mkdirSync30(projectsDir, { recursive: true });
@@ -79010,7 +79074,7 @@ async function runLocalStudioMode(dir, options) {
 }
 async function runEmbeddedMode(dir, startPort, options) {
   const { createStudioServer: createStudioServer2, loadPreviewServerBuildSignature: loadPreviewServerBuildSignature2, resolveStudioBundle: resolveStudioBundle2 } = await Promise.resolve().then(() => (init_studioServer(), studioServer_exports));
-  const pName = options?.projectName ?? basename6(dir);
+  const pName = options?.projectName ?? basename7(dir);
   const studioBundle = resolveStudioBundle2();
   ge(c2.bold("hyperframes preview"));
   const s2 = ft();
@@ -79240,7 +79304,7 @@ var init_preview2 = __esm({
         const rawArg = args.dir;
         const dir = resolve25(rawArg ?? ".");
         const isImplicitCwd = !rawArg || rawArg === "." || rawArg === "./";
-        const projectName = isImplicitCwd ? basename6(process.env.PWD ?? dir) : basename6(dir);
+        const projectName = isImplicitCwd ? basename7(process.env.PWD ?? dir) : basename7(dir);
         const indexPath = join59(dir, "index.html");
         if (existsSync49(indexPath)) {
           const project = { dir, name: projectName, indexPath };
@@ -79328,7 +79392,7 @@ import {
   readFileSync as readFileSync36,
   readdirSync as readdirSync21
 } from "fs";
-import { resolve as resolve26, basename as basename7, join as join60, dirname as dirname20 } from "path";
+import { resolve as resolve26, basename as basename8, join as join60, dirname as dirname20 } from "path";
 import { fileURLToPath as fileURLToPath7 } from "url";
 import { execFileSync as execFileSync5, spawn as spawn12 } from "child_process";
 function probeVideo(filePath) {
@@ -79409,7 +79473,7 @@ function getSharedTemplateDir() {
   return resolveAssetDir(["..", "templates", "_shared"], ["templates", "_shared"]);
 }
 function toPackageName(projectName) {
-  const normalized = basename7(projectName).trim().toLowerCase().replace(/^[._]+/, "").replace(/[^a-z0-9._~-]+/g, "-").replace(/-+/g, "-").replace(/^[-.]+|[-.]+$/g, "");
+  const normalized = basename8(projectName).trim().toLowerCase().replace(/^[._]+/, "").replace(/[^a-z0-9._~-]+/g, "-").replace(/-+/g, "-").replace(/^[-.]+|[-.]+$/g, "");
   return normalized || "hyperframes-project";
 }
 function getHyperframesPackageSpecifier() {
@@ -79520,7 +79584,7 @@ async function patchTranscript(dir, transcriptPath) {
 async function handleVideoFile(videoPath, destDir, interactive) {
   const probed = probeVideo(videoPath);
   let meta = { ...DEFAULT_META };
-  let localVideoName = basename7(videoPath);
+  let localVideoName = basename8(videoPath);
   if (probed) {
     meta = probed;
     if (interactive) {
@@ -79870,8 +79934,8 @@ var init_init = __esm({
               process.exit(1);
             }
             sourceFilePath2 = audioPath;
-            copyFileSync5(audioPath, resolve26(destDir2, basename7(audioPath)));
-            console.log(`Audio: ${basename7(audioPath)}`);
+            copyFileSync5(audioPath, resolve26(destDir2, basename8(audioPath)));
+            console.log(`Audio: ${basename8(audioPath)}`);
           }
           if (sourceFilePath2 && !skipTranscribe) {
             try {
@@ -79895,7 +79959,7 @@ var init_init = __esm({
           try {
             await scaffoldProject(
               destDir2,
-              basename7(destDir2),
+              basename8(destDir2),
               templateId2,
               localVideoName2,
               videoDuration2,
@@ -80002,8 +80066,8 @@ var init_init = __esm({
           }
           mkdirSync31(destDir, { recursive: true });
           sourceFilePath = audioPath;
-          copyFileSync5(audioPath, resolve26(destDir, basename7(audioPath)));
-          R2.info(`Audio copied to ${c2.accent(basename7(audioPath))}`);
+          copyFileSync5(audioPath, resolve26(destDir, basename8(audioPath)));
+          R2.info(`Audio copied to ${c2.accent(basename8(audioPath))}`);
         }
         if (sourceFilePath) {
           const transcribeChoice = await ue({
@@ -80565,10 +80629,10 @@ var init_format = __esm({
 
 // src/utils/project.ts
 import { existsSync as existsSync52, statSync as statSync18 } from "fs";
-import { resolve as resolve29, basename as basename8 } from "path";
+import { resolve as resolve29, basename as basename9 } from "path";
 function resolveProject(dirArg) {
   const dir = resolve29(dirArg ?? ".");
-  const name = basename8(dir);
+  const name = basename9(dir);
   const indexPath = resolve29(dir, "index.html");
   if (!existsSync52(dir) || !statSync18(dir).isDirectory()) {
     errorBox("Not a directory: " + dir);
@@ -80860,7 +80924,7 @@ var init_play = __esm({
 });
 
 // src/utils/publishProject.ts
-import { basename as basename9, join as join61, relative as relative9 } from "path";
+import { basename as basename10, join as join61, relative as relative9 } from "path";
 import { readdirSync as readdirSync22, readFileSync as readFileSync38, statSync as statSync19 } from "fs";
 import AdmZip from "adm-zip";
 function isRecord2(value) {
@@ -81074,7 +81138,7 @@ async function publishProjectArchiveStaged(apiBaseUrl2, title, archive) {
   return publishedProject;
 }
 async function publishProjectArchive(projectDir) {
-  const title = basename9(projectDir);
+  const title = basename10(projectDir);
   const archive = createPublishArchive(projectDir);
   const apiBaseUrl2 = getPublishApiBaseUrl();
   const stagedResult = await publishProjectArchiveStaged(apiBaseUrl2, title, archive);
@@ -81100,7 +81164,7 @@ __export(publish_exports, {
   default: () => publish_default,
   examples: () => examples6
 });
-import { basename as basename10, resolve as resolve31 } from "path";
+import { basename as basename11, resolve as resolve31 } from "path";
 import { existsSync as existsSync54 } from "fs";
 import { join as join62 } from "path";
 var examples6, publish_default;
@@ -81136,7 +81200,7 @@ var init_publish = __esm({
         const rawArg = args.dir;
         const dir = resolve31(rawArg ?? ".");
         const isImplicitCwd = !rawArg || rawArg === "." || rawArg === "./";
-        const projectName = isImplicitCwd ? basename10(process.env["PWD"] ?? dir) : basename10(dir);
+        const projectName = isImplicitCwd ? basename11(process.env["PWD"] ?? dir) : basename11(dir);
         const indexPath = join62(dir, "index.html");
         if (existsSync54(indexPath)) {
           const lintResult = await lintProject({ dir, name: projectName, indexPath });
@@ -81559,7 +81623,7 @@ __export(render_exports, {
 });
 import { mkdirSync as mkdirSync32, readdirSync as readdirSync23, readFileSync as readFileSync40, statSync as statSync20, writeFileSync as writeFileSync27, rmSync as rmSync14 } from "fs";
 import { cpus as cpus4, freemem as freemem4, tmpdir as tmpdir5 } from "os";
-import { resolve as resolve33, dirname as dirname22, join as join63, basename as basename11 } from "path";
+import { resolve as resolve33, dirname as dirname22, join as join63, basename as basename12 } from "path";
 import { execFileSync as execFileSync6, spawn as spawn13 } from "child_process";
 function formatFpsParseError(input2, reason) {
   switch (reason) {
@@ -81663,7 +81727,7 @@ async function renderDocker(projectDir, outputPath, options) {
     process.exit(1);
   }
   const outputDir = dirname22(outputPath);
-  const outputFilename = basename11(outputPath);
+  const outputFilename = basename12(outputPath);
   const dockerArgs = buildDockerRunArgs({
     imageTag,
     projectDir: resolve33(projectDir),
@@ -84652,7 +84716,7 @@ __export(synthesize_exports, {
 });
 import { execFileSync as execFileSync7 } from "child_process";
 import { existsSync as existsSync63, writeFileSync as writeFileSync29, mkdirSync as mkdirSync35, readdirSync as readdirSync25, unlinkSync as unlinkSync6 } from "fs";
-import { join as join70, dirname as dirname26, basename as basename12 } from "path";
+import { join as join70, dirname as dirname26, basename as basename13 } from "path";
 import { homedir as homedir11 } from "os";
 function findPython() {
   for (const name of ["python3", "python"]) {
@@ -84691,7 +84755,7 @@ function ensureSynthScript() {
   if (!existsSync63(SCRIPT_PATH)) {
     mkdirSync35(SCRIPT_DIR, { recursive: true });
     writeFileSync29(SCRIPT_PATH, SYNTH_SCRIPT);
-    const currentName = basename12(SCRIPT_PATH);
+    const currentName = basename13(SCRIPT_PATH);
     try {
       for (const entry of readdirSync25(SCRIPT_DIR)) {
         if (entry !== currentName && /^synth(-v\d+)?\.py$/.test(entry)) {
@@ -85963,7 +86027,7 @@ __export(contactSheet_exports, {
 });
 import sharp from "sharp";
 import { readdirSync as readdirSync26, readFileSync as readFileSync48, writeFileSync as writeFileSync30, unlinkSync as unlinkSync7, existsSync as existsSync67 } from "fs";
-import { join as join73, extname as extname13, basename as basename13, dirname as dirname29 } from "path";
+import { join as join73, extname as extname13, basename as basename14, dirname as dirname29 } from "path";
 async function createContactSheet(imagePaths, outputPath, opts = {}) {
   const {
     cols = 3,
@@ -85996,7 +86060,7 @@ async function createContactSheet(imagePaths, outputPath, opts = {}) {
     overlays.push({ input: resized, left: x3, top: y + labelH });
     let labelText = `${i2 + 1}`;
     if (labelMode === "filename") {
-      labelText = `${i2 + 1}. ${basename13(files[i2]).replace(extname13(files[i2]), "")}`;
+      labelText = `${i2 + 1}. ${basename14(files[i2]).replace(extname13(files[i2]), "")}`;
     } else if (labelMode === "custom" && labels?.[i2]) {
       labelText = `${i2 + 1}. ${labels[i2]}`;
     }
@@ -93094,7 +93158,7 @@ var require_node_domexception = __commonJS({
 
 // ../../node_modules/.bun/fetch-blob@3.2.0/node_modules/fetch-blob/from.js
 import { statSync as statSync23, createReadStream as createReadStream2, promises as fs2 } from "fs";
-import { basename as basename14 } from "path";
+import { basename as basename15 } from "path";
 var import_node_domexception, stat, blobFromSync, blobFrom, fileFrom, fileFromSync, fromBlob, fromFile, BlobDataItem;
 var init_from = __esm({
   "../../node_modules/.bun/fetch-blob@3.2.0/node_modules/fetch-blob/from.js"() {
@@ -93118,7 +93182,7 @@ var init_from = __esm({
       size: stat3.size,
       lastModified: stat3.mtimeMs,
       start: 0
-    })], basename14(path2), { type, lastModified: stat3.mtimeMs });
+    })], basename15(path2), { type, lastModified: stat3.mtimeMs });
     BlobDataItem = class _BlobDataItem {
       #path;
       #start;
@@ -131852,6 +131916,57 @@ ${HELP}`);
   }
 });
 
+// src/cloud/detectAspectRatio.ts
+import { readFileSync as readFileSync58 } from "fs";
+function extractAttributeNumber(tag, re2) {
+  const match = tag.match(re2);
+  if (!match) return null;
+  const raw = match[1] ?? match[2] ?? match[3];
+  if (raw === void 0) return null;
+  const value = Number(raw);
+  return Number.isFinite(value) ? value : null;
+}
+function detectAspectRatioFromHtml(entryHtmlPath) {
+  let html;
+  try {
+    html = readFileSync58(entryHtmlPath, "utf-8");
+  } catch (err) {
+    return { kind: "read-error", error: err instanceof Error ? err.message : String(err) };
+  }
+  return detectAspectRatioFromHtmlString(html);
+}
+function detectAspectRatioFromHtmlString(html) {
+  const tagMatch = html.match(ROOT_COMPOSITION_DIV_RE);
+  if (!tagMatch) return { kind: "no-root-div" };
+  const openTag = tagMatch[0];
+  const width = extractAttributeNumber(openTag, DATA_WIDTH_RE);
+  const height = extractAttributeNumber(openTag, DATA_HEIGHT_RE);
+  if (width === null || height === null) return { kind: "no-dims" };
+  if (width <= 0 || height <= 0) return { kind: "invalid-dims", width, height };
+  const ratio = width / height;
+  for (const candidate of SUPPORTED_RATIOS) {
+    if (Math.abs(ratio - candidate.ratio) <= RATIO_TOLERANCE) {
+      return { kind: "matched", aspectRatio: candidate.value, width, height };
+    }
+  }
+  return { kind: "no-match", width, height, ratio };
+}
+var RATIO_TOLERANCE, SUPPORTED_RATIOS, ROOT_COMPOSITION_DIV_RE, DATA_WIDTH_RE, DATA_HEIGHT_RE;
+var init_detectAspectRatio = __esm({
+  "src/cloud/detectAspectRatio.ts"() {
+    "use strict";
+    RATIO_TOLERANCE = 0.05;
+    SUPPORTED_RATIOS = [
+      { value: "16:9", ratio: 16 / 9 },
+      { value: "9:16", ratio: 9 / 16 },
+      { value: "1:1", ratio: 1 }
+    ];
+    ROOT_COMPOSITION_DIV_RE = /<div\b[^>]*?\bdata-composition-id\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)[^>]*>/i;
+    DATA_WIDTH_RE = /\bdata-width\s*=\s*(?:"(\d+(?:\.\d+)?)"|'(\d+(?:\.\d+)?)'|(\d+(?:\.\d+)?))(?=\s|>|\/)/i;
+    DATA_HEIGHT_RE = /\bdata-height\s*=\s*(?:"(\d+(?:\.\d+)?)"|'(\d+(?:\.\d+)?)'|(\d+(?:\.\d+)?))(?=\s|>|\/)/i;
+  }
+});
+
 // src/cloud/poll.ts
 function isTerminal(status) {
   return TERMINAL_STATUSES.has(status);
@@ -133307,6 +133422,40 @@ function resolveProjectInput(opts) {
   if (explicit.url) return { kind: "url", url: opts.url };
   return { kind: "dir", dir: opts.dir ?? "." };
 }
+function maybeAutoDetectAspectRatio(project, compositionArg, asJson) {
+  if (project.kind !== "dir") {
+    const reason = project.kind === "asset_id" ? "--asset-id" : "--url";
+    logDetection(asJson, `Auto-detect skipped (project is ${reason})`);
+    return void 0;
+  }
+  const dir = project.dir ?? ".";
+  const entryRelative = compositionArg ?? "index.html";
+  const entryPath = resolvePath4(dir, entryRelative);
+  const detection = detectAspectRatioFromHtml(entryPath);
+  logDetection(asJson, summarizeDetection(detection, entryRelative));
+  return detection.kind === "matched" ? detection.aspectRatio : void 0;
+}
+function logDetection(asJson, message) {
+  if (asJson) return;
+  const suffix = message.startsWith("Detected aspect ratio") ? "" : `; ${ASPECT_FALLBACK_HINT}`;
+  console.log(c2.dim(`   ${message}${suffix}`));
+}
+function summarizeDetection(detection, entryRelative) {
+  switch (detection.kind) {
+    case "matched":
+      return `Detected aspect ratio: ${detection.aspectRatio} (from ${entryRelative} dims ${detection.width}\xD7${detection.height})`;
+    case "no-root-div":
+      return `No <div data-composition-id> found in ${entryRelative}`;
+    case "no-dims":
+      return `${entryRelative} root composition has no data-width / data-height`;
+    case "invalid-dims":
+      return `${entryRelative} root has invalid dims (${detection.width}\xD7${detection.height})`;
+    case "no-match":
+      return `${entryRelative} dims ${detection.width}\xD7${detection.height} (ratio ${detection.ratio.toFixed(2)}) don't match 16:9, 9:16, or 1:1`;
+    case "read-error":
+      return `Couldn't read ${entryRelative} for aspect-ratio detection (${detection.error})`;
+  }
+}
 function resolveVariablesAndValidateIfLocal(inline, filePath, strict, source) {
   const variables = resolveVariablesArg(inline, filePath);
   if (!variables || Object.keys(variables).length === 0) return variables;
@@ -133384,6 +133533,7 @@ function buildRenderBody(opts) {
   if (opts.quality !== void 0) body.quality = opts.quality;
   if (opts.format !== void 0) body.format = opts.format;
   if (opts.resolution !== void 0) body.resolution = opts.resolution;
+  if (opts.aspectRatio !== void 0) body.aspect_ratio = opts.aspectRatio;
   if (opts.composition !== void 0) body.composition = opts.composition;
   if (opts.variables !== void 0) body.variables = opts.variables;
   if (opts.title !== void 0) body.title = opts.title;
@@ -133476,11 +133626,12 @@ async function streamVideo(url, destPath, asJson) {
     process.exit(1);
   }
 }
-var VALID_QUALITY2, VALID_FORMAT2, VALID_RESOLUTION, FORMAT_EXT2, examples26, render_default2, IDEMPOTENCY_KEY_RE;
+var VALID_QUALITY2, VALID_FORMAT2, VALID_RESOLUTION, VALID_ASPECT_RATIO, FORMAT_EXT2, examples26, render_default2, IDEMPOTENCY_KEY_RE, ASPECT_FALLBACK_HINT;
 var init_render4 = __esm({
   "src/commands/cloud/render.ts"() {
     "use strict";
     init_dist();
+    init_detectAspectRatio();
     init_colors();
     init_format();
     init_project();
@@ -133493,14 +133644,8 @@ var init_render4 = __esm({
     init_statusColor();
     VALID_QUALITY2 = ["draft", "standard", "high"];
     VALID_FORMAT2 = ["mp4", "webm", "mov"];
-    VALID_RESOLUTION = [
-      "landscape",
-      "portrait",
-      "landscape-4k",
-      "portrait-4k",
-      "square",
-      "square-4k"
-    ];
+    VALID_RESOLUTION = ["1080p", "4k"];
+    VALID_ASPECT_RATIO = ["16:9", "9:16", "1:1"];
     FORMAT_EXT2 = { mp4: ".mp4", webm: ".webm", mov: ".mov" };
     examples26 = [
       ["Render the current directory in the cloud", "hyperframes cloud render"],
@@ -133528,7 +133673,11 @@ var init_render4 = __esm({
         format: { type: "string", description: "mp4 | webm | mov (default: mp4)" },
         resolution: {
           type: "string",
-          description: "Resolution preset: landscape | portrait | landscape-4k | portrait-4k | square | square-4k"
+          description: "Resolution tier: 1080p | 4k (default: 1080p; 4k is billed at 1.5x)"
+        },
+        "aspect-ratio": {
+          type: "string",
+          description: "Aspect ratio: 16:9 | 9:16 | 1:1 (default: 16:9)"
         },
         composition: {
           type: "string",
@@ -133611,6 +133760,9 @@ var init_render4 = __esm({
         const resolution = parseEnumFlag(args.resolution, VALID_RESOLUTION, {
           flag: "--resolution"
         });
+        const explicitAspectRatio = parseEnumFlag(args["aspect-ratio"], VALID_ASPECT_RATIO, {
+          flag: "--aspect-ratio"
+        });
         const pollIntervalMs = parsePollIntervalMs(args["poll-interval"]);
         const maxWaitMs = parseMaxWaitMs(args["max-wait"]);
         validateIdempotencyKey(args["idempotency-key"]);
@@ -133619,6 +133771,7 @@ var init_render4 = __esm({
           assetId: args["asset-id"],
           url: args.url
         });
+        const aspectRatio = explicitAspectRatio ?? maybeAutoDetectAspectRatio(project, args.composition, asJson);
         const variables = resolveVariablesAndValidateIfLocal(
           args.variables,
           args["variables-file"],
@@ -133633,6 +133786,7 @@ var init_render4 = __esm({
           quality,
           format,
           resolution,
+          aspectRatio,
           composition: args.composition,
           variables,
           title: args.title,
@@ -133693,6 +133847,7 @@ var init_render4 = __esm({
       }
     });
     IDEMPOTENCY_KEY_RE = /^[A-Za-z0-9_:.-]{1,255}$/;
+    ASPECT_FALLBACK_HINT = "server will default aspect_ratio to 16:9. Pass --aspect-ratio to override.";
   }
 });
 
@@ -135077,10 +135232,10 @@ if (rootVersionRequested) {
   process.exit(0);
 }
 try {
-  const { readFileSync: readFileSync58 } = await import("fs");
+  const { readFileSync: readFileSync59 } = await import("fs");
   const { resolve: resolve46 } = await import("path");
   const envPath = resolve46(process.cwd(), ".env");
-  const envContent = readFileSync58(envPath, "utf-8");
+  const envContent = readFileSync59(envPath, "utf-8");
   for (const rawLine of envContent.split("\n")) {
     let line = rawLine.trim();
     if (!line || line.startsWith("#")) continue;

package/dist/skills/hyperframes/references/techniques.md

@@ -181,38 +181,23 @@ The slide distance DECAYS per word (80→12px) — mimics a camera settling.
 Vector animations that play inside a composition. Use for logos, character animations, icons.
 
 ```html
-<!-- The web-component package is `@lottiefiles/dotlottie-wc` (the SDK
-     `@lottiefiles/dotlottie-web` does NOT expose a custom element).
-     The element tag is <dotlottie-wc>. -->
-<script
-  src="https://cdn.jsdelivr.net/npm/@lottiefiles/dotlottie-wc/dist/dotlottie-wc.js"
-  type="module"
-></script>
-<dotlottie-wc
-  class="lottie"
-  src="capture/assets/lottie/animation-0.json"
-  autoplay
-  loop
-  speed="1.5"
-  style="width:500px;height:500px;"
->
-</dotlottie-wc>
+<div id="anim" class="lottie"></div>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/bodymovin/5.12.2/lottie.min.js"></script>
 <script>
-  gsap.set(".lottie", { scale: 0.3, opacity: 0 });
-  tl.to(".lottie", { scale: 1, opacity: 1, duration: 0.35, ease: "back.out(1.6)" }, 0.2);
-</script>
-```
-
-Or use lottie-web for more control:
+  window.__hfLottie = window.__hfLottie || [];
+
+  const anim = lottie.loadAnimation({
+    container: document.getElementById("anim"),
+    renderer: "svg",
+    loop: false,
+    autoplay: false,
+    path: "capture/assets/lottie/animation-0.json",
+  });
+  window.__hfLottie.push(anim);
 
-```javascript
-var anim = lottie.loadAnimation({
-  container: document.getElementById("anim"),
-  renderer: "svg",
-  loop: false,
-  autoplay: false,
-  path: "capture/assets/lottie/animation-0.json",
-});
+  gsap.set("#anim", { scale: 0.3, opacity: 0 });
+  tl.to("#anim", { scale: 1, opacity: 1, duration: 0.35, ease: "back.out(1.6)" }, 0.2);
+</script>
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyperframes",
-  "version": "0.6.63",
+  "version": "0.6.65",
   "description": "HyperFrames CLI — create, preview, and render HTML video compositions",
   "repository": {
     "type": "git",