hyperframes 0.4.39 → 0.4.41

package/dist/cli.js

@@ -54,7 +54,7 @@ var VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    VERSION = true ? "0.4.39" : "0.0.0-dev";
+    VERSION = true ? "0.4.41" : "0.0.0-dev";
   }
 });
 
@@ -10206,8 +10206,8 @@ function trackRenderError(props) {
     memory_free_mb: props.memoryFreeMb
   });
 }
-function trackInitTemplate(templateId) {
-  trackEvent("init_template", { template: templateId });
+function trackInitTemplate(templateId, props) {
+  trackEvent("init_template", { template: templateId, tailwind: props?.tailwind });
 }
 function trackBrowserInstall() {
   trackEvent("browser_install", {});
@@ -25516,6 +25516,13 @@ function resolveConfig(overrides) {
       "PRODUCER_ENABLE_STREAMING_ENCODE",
       DEFAULT_CONFIG2.enableStreamingEncode
     ),
+    streamingEncodeMaxDurationSeconds: Math.max(
+      0,
+      envNum(
+        "PRODUCER_STREAMING_ENCODE_MAX_DURATION_SECONDS",
+        DEFAULT_CONFIG2.streamingEncodeMaxDurationSeconds
+      )
+    ),
     ffmpegEncodeTimeout: envNum("FFMPEG_ENCODE_TIMEOUT_MS", DEFAULT_CONFIG2.ffmpegEncodeTimeout),
     ffmpegProcessTimeout: envNum("FFMPEG_PROCESS_TIMEOUT_MS", DEFAULT_CONFIG2.ffmpegProcessTimeout),
     ffmpegStreamingTimeout: envNum(
@@ -25573,7 +25580,8 @@ var init_config2 = __esm({
       forceScreenshot: false,
       enableChunkedEncode: false,
       chunkSizeFrames: 360,
-      enableStreamingEncode: false,
+      enableStreamingEncode: true,
+      streamingEncodeMaxDurationSeconds: 240,
       ffmpegEncodeTimeout: 6e5,
       ffmpegProcessTimeout: 3e5,
       ffmpegStreamingTimeout: 6e5,
@@ -26182,6 +26190,44 @@ async function pollPageExpression(page, expression, timeoutMs, intervalMs = 100)
   }
   return Boolean(await page.evaluate(expression));
 }
+async function applyVideoMetadataHints(page, hints) {
+  if (!hints || hints.length === 0) return;
+  await page.evaluate(
+    (metadataHints) => {
+      for (const hint of metadataHints) {
+        if (!hint.id || !Number.isFinite(hint.width) || !Number.isFinite(hint.height) || hint.width <= 0 || hint.height <= 0) {
+          continue;
+        }
+        const video = document.getElementById(hint.id);
+        if (!video) continue;
+        if (!video.hasAttribute("width")) video.setAttribute("width", String(hint.width));
+        if (!video.hasAttribute("height")) video.setAttribute("height", String(hint.height));
+        const computed = window.getComputedStyle(video);
+        if (!video.style.aspectRatio && (!computed.aspectRatio || computed.aspectRatio === "auto")) {
+          video.style.aspectRatio = `${hint.width} / ${hint.height}`;
+        }
+      }
+    },
+    [...hints]
+  );
+}
+async function waitForOptionalTailwindReady(page, timeoutMs) {
+  const hasTailwindReady = await page.evaluate(
+    `(() => { const ready = window.__tailwindReady; return !!ready && typeof ready.then === "function"; })()`
+  );
+  if (!hasTailwindReady) return;
+  const ready = await Promise.race([
+    page.evaluate(
+      `Promise.resolve(window.__tailwindReady).then(() => true, () => false)`
+    ),
+    new Promise((resolve39) => setTimeout(() => resolve39(false), timeoutMs))
+  ]);
+  if (!ready) {
+    throw new Error(
+      `[FrameCapture] window.__tailwindReady not resolved after ${timeoutMs}ms. Tailwind browser runtime must finish before frame capture starts.`
+    );
+  }
+}
 async function initializeSession(session) {
   const { page, serverUrl } = session;
   page.on("console", (msg) => {
@@ -26225,6 +26271,7 @@ async function initializeSession(session) {
         `[FrameCapture] window.__hf not ready after ${pageReadyTimeout2}ms. Page must expose window.__hf = { duration, seek }.`
       );
     }
+    await applyVideoMetadataHints(page, session.options.videoMetadataHints);
     const skipIdsLiteral = JSON.stringify(session.options.skipReadinessVideoIds ?? []);
     const videosReady = await pollPageExpression(
       page,
@@ -26237,6 +26284,7 @@ async function initializeSession(session) {
       );
     }
     await page.evaluate(`document.fonts?.ready`);
+    await waitForOptionalTailwindReady(page, pageReadyTimeout2);
     if (session.options.format === "png") {
       await initTransparentBackground(session.page);
     }
@@ -26291,6 +26339,7 @@ async function initializeSession(session) {
       `[FrameCapture] window.__hf not ready after ${pageReadyTimeout}ms. Page must expose window.__hf = { duration, seek }.`
     );
   }
+  await applyVideoMetadataHints(page, session.options.videoMetadataHints);
   const beginframeSkipIdsLiteral = JSON.stringify(session.options.skipReadinessVideoIds ?? []);
   const videoDeadline = Date.now() + (session.config?.playerReadyTimeout ?? DEFAULT_CONFIG2.playerReadyTimeout);
   while (Date.now() < videoDeadline) {
@@ -26301,6 +26350,7 @@ async function initializeSession(session) {
     await new Promise((r2) => setTimeout(r2, 100));
   }
   await page.evaluate(`document.fonts?.ready`);
+  await waitForOptionalTailwindReady(page, pageReadyTimeout);
   warmupRunning = false;
   session.beginFrameTimeTicks = (warmupTicks + 10) * session.beginFrameIntervalMs;
   if (session.options.format === "png") {
@@ -34108,6 +34158,24 @@ function applyRenderModeHints(cfg, compiled, log2 = defaultLogger) {
     reasons: compiled.renderModeHints.reasons.map((reason) => reason.message)
   });
 }
+function collectVideoReadinessSkipIds(nativeHdrVideoIds, extractedVideos) {
+  return Array.from(
+    /* @__PURE__ */ new Set([
+      ...nativeHdrVideoIds,
+      ...extractedVideos.filter((video) => hasUsableVideoDimensions(video.metadata)).map((video) => video.videoId)
+    ])
+  ).sort();
+}
+function hasUsableVideoDimensions(metadata) {
+  return Number.isFinite(metadata.width) && Number.isFinite(metadata.height) && metadata.width > 0 && metadata.height > 0;
+}
+function collectVideoMetadataHints(extractedVideos) {
+  return extractedVideos.filter((video) => hasUsableVideoDimensions(video.metadata)).map((video) => ({
+    id: video.videoId,
+    width: video.metadata.width,
+    height: video.metadata.height
+  })).sort((a, b) => a.id.localeCompare(b.id));
+}
 function resolveRenderWorkerCount(totalFrames, requestedWorkers, cfg, compiled, composition, log2 = defaultLogger, measuredCaptureCost) {
   const captureCost = combineCaptureCostEstimates(
     estimateCaptureCostMultiplier(compiled, composition),
@@ -34770,6 +34838,27 @@ function createRenderJob(config) {
 function normalizeCompositionSrcPath(srcPath) {
   return srcPath.replace(/\\/g, "/").replace(/^\.\//, "");
 }
+function createStandaloneEntryRenderClone(root, host) {
+  const hostClone = host.cloneNode(true);
+  hostClone.setAttribute("data-start", "0");
+  if (root === host) return hostClone;
+  const rootClone = root.cloneNode(false);
+  rootClone.appendChild(hostClone);
+  return rootClone;
+}
+function replaceBodyWithRenderClone(body, renderClone) {
+  while (body.firstChild) {
+    body.removeChild(body.firstChild);
+  }
+  body.appendChild(renderClone);
+}
+function shouldUseStreamingEncode(cfg, outputFormat, workerCount, durationSeconds) {
+  if (!cfg.enableStreamingEncode) return false;
+  if (outputFormat === "png-sequence") return false;
+  if (!Number.isFinite(durationSeconds) || durationSeconds <= 0) return false;
+  if (durationSeconds > cfg.streamingEncodeMaxDurationSeconds) return false;
+  return workerCount === 1;
+}
 function extractStandaloneEntryFromIndex(indexHtml, entryFile) {
   const normalizedEntryFile = normalizeCompositionSrcPath(entryFile);
   const { document: document2 } = parseHTML(indexHtml);
@@ -34784,16 +34873,8 @@ function extractStandaloneEntryFromIndex(indexHtml, entryFile) {
     (candidate) => candidate.hasAttribute("data-composition-id")
   ) ?? null;
   if (!root) return null;
-  const hostClone = host.cloneNode(true);
-  hostClone.setAttribute("data-start", "0");
-  body.innerHTML = "";
-  if (root === host) {
-    body.appendChild(hostClone);
-    return document2.toString();
-  }
-  const rootClone = root.cloneNode(false);
-  rootClone.appendChild(hostClone);
-  body.appendChild(rootClone);
+  const renderClone = createStandaloneEntryRenderClone(root, host);
+  replaceBodyWithRenderClone(body, renderClone);
   return document2.toString();
 }
 async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSignal) {
@@ -34825,7 +34906,6 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
   }
   const enableChunkedEncode = cfg.enableChunkedEncode;
   const chunkedEncodeSize = cfg.chunkSizeFrames;
-  const enableStreamingEncode = cfg.enableStreamingEncode && !isPngSequence;
   let peakRssBytes = 0;
   let peakHeapUsedBytes = 0;
   const sampleMemory = () => {
@@ -35119,6 +35199,8 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
     let frameLookup = null;
     const compiledDir = join35(workDir, "compiled");
     let extractionResult = null;
+    let videoReadinessSkipIds = [];
+    let videoMetadataHints = [];
     const nativeHdrVideoIds = /* @__PURE__ */ new Set();
     const videoTransfers = /* @__PURE__ */ new Map();
     if (job.config.hdrMode !== "force-sdr" && composition.videos.length > 0) {
@@ -35175,6 +35257,11 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
       if (extractionResult.extracted.length > 0) {
         frameLookup = createFrameLookupTable(composition.videos, extractionResult.extracted);
       }
+      videoReadinessSkipIds = collectVideoReadinessSkipIds(
+        nativeHdrVideoIds,
+        extractionResult.extracted
+      );
+      videoMetadataHints = collectVideoMetadataHints(extractionResult.extracted);
       perfStages.videoExtractMs = Date.now() - stage2Start;
       const existingAudioSrcs = new Set(composition.audios.map((a) => a.src));
       for (const ext of extractionResult.extracted) {
@@ -35288,9 +35375,10 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
       format: needsAlpha ? "png" : "jpeg",
       quality: needsAlpha ? void 0 : job.config.quality === "draft" ? 80 : 95
     };
-    const buildHdrCaptureOptions = () => ({
+    const buildCaptureOptions = () => ({
       ...captureOptions,
-      skipReadinessVideoIds: Array.from(nativeHdrVideoIds)
+      videoMetadataHints,
+      skipReadinessVideoIds: videoReadinessSkipIds
     });
     let captureCalibration;
     let switchedToScreenshotAfterCalibration = false;
@@ -35303,7 +35391,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
         calibrationSession = await createCaptureSession(
           fileServer.url,
           calibrationDir,
-          buildHdrCaptureOptions(),
+          buildCaptureOptions(),
           videoInjector,
           calibrationCfg
         );
@@ -35386,6 +35474,15 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
       await closeCaptureSession(probeSession);
       probeSession = null;
     }
+    let useStreamingEncode = shouldUseStreamingEncode(cfg, outputFormat, workerCount, job.duration);
+    log2.info("streaming-encode gate", {
+      enabled: useStreamingEncode,
+      configFlag: cfg.enableStreamingEncode,
+      outputFormat,
+      workerCount,
+      durationSeconds: job.duration,
+      maxDurationSeconds: cfg.streamingEncodeMaxDurationSeconds
+    });
     const captureAttempts = [];
     const FORMAT_EXT2 = {
       mp4: ".mp4",
@@ -35427,7 +35524,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
       const domSession = await createCaptureSession(
         fileServer.url,
         framesDir,
-        buildHdrCaptureOptions(),
+        buildCaptureOptions(),
         createVideoFrameInjector(frameLookup),
         cfg
       );
@@ -35925,28 +36022,47 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
     } else {
       let streamingEncoder = null;
       let streamingEncoderClosed = false;
-      if (enableStreamingEncode) {
-        streamingEncoder = await spawnStreamingEncoder(
-          videoOnlyPath,
-          {
-            fps: job.config.fps,
-            width,
-            height,
-            codec: preset.codec,
-            preset: preset.preset,
-            quality: effectiveQuality,
-            bitrate: effectiveBitrate,
-            pixelFormat: preset.pixelFormat,
-            useGpu: job.config.useGpu,
-            imageFormat: captureOptions.format || "jpeg",
-            hdr: preset.hdr
-          },
-          abortSignal
-        );
-        assertNotAborted();
+      if (useStreamingEncode) {
+        try {
+          streamingEncoder = await spawnStreamingEncoder(
+            videoOnlyPath,
+            {
+              fps: job.config.fps,
+              width,
+              height,
+              codec: preset.codec,
+              preset: preset.preset,
+              quality: effectiveQuality,
+              bitrate: effectiveBitrate,
+              pixelFormat: preset.pixelFormat,
+              useGpu: job.config.useGpu,
+              imageFormat: captureOptions.format || "jpeg",
+              hdr: preset.hdr
+            },
+            abortSignal
+          );
+          assertNotAborted();
+        } catch (err) {
+          if (abortSignal?.aborted) {
+            if (streamingEncoder && !streamingEncoderClosed) {
+              await streamingEncoder.close().catch(() => {
+              });
+              streamingEncoderClosed = true;
+            }
+            throw err;
+          }
+          useStreamingEncode = false;
+          streamingEncoder = null;
+          log2.warn("[Render] Streaming encoder spawn failed; falling back to disk-frame encode.", {
+            error: err instanceof Error ? err.message : String(err),
+            outputFormat,
+            workerCount,
+            durationSeconds: job.duration
+          });
+        }
       }
       try {
-        if (enableStreamingEncode && streamingEncoder) {
+        if (useStreamingEncode && streamingEncoder) {
           const reorderBuffer = createFrameReorderBuffer(0, totalFrames);
           const currentEncoder = streamingEncoder;
           if (workerCount > 1) {
@@ -35960,7 +36076,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
               fileServer.url,
               workDir,
               tasks,
-              buildHdrCaptureOptions(),
+              buildCaptureOptions(),
               () => createVideoFrameInjector(frameLookup),
               abortSignal,
               (progress) => {
@@ -35990,7 +36106,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
             const session = probeSession ?? await createCaptureSession(
               fileServer.url,
               framesDir,
-              buildHdrCaptureOptions(),
+              buildCaptureOptions(),
               videoInjector,
               cfg
             );
@@ -36045,7 +36161,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
               initialWorkerCount: workerCount,
               allowRetry: job.config.workers === void 0,
               frameExt: needsAlpha ? "png" : "jpg",
-              captureOptions: buildHdrCaptureOptions(),
+              captureOptions: buildCaptureOptions(),
               createBeforeCaptureHook: () => createVideoFrameInjector(frameLookup),
               abortSignal,
               onProgress: (progress) => {
@@ -36080,7 +36196,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
             const session = probeSession ?? await createCaptureSession(
               fileServer.url,
               framesDir,
-              buildHdrCaptureOptions(),
+              buildCaptureOptions(),
               videoInjector,
               cfg
             );
@@ -37784,7 +37900,8 @@ var init_preview2 = __esm({
 var init_exports = {};
 __export(init_exports, {
   default: () => init_default,
-  examples: () => examples2
+  examples: () => examples2,
+  injectTailwindBrowserScript: () => injectTailwindBrowserScript
 });
 import {
   existsSync as existsSync38,
@@ -37875,6 +37992,92 @@ function getStaticTemplateDir(templateId) {
 function getSharedTemplateDir() {
   return resolveAssetDir(["..", "templates", "_shared"], ["templates", "_shared"]);
 }
+function toPackageName(projectName) {
+  const normalized = basename5(projectName).trim().toLowerCase().replace(/^[._]+/, "").replace(/[^a-z0-9._~-]+/g, "-").replace(/-+/g, "-").replace(/^[-.]+|[-.]+$/g, "");
+  return normalized || "hyperframes-project";
+}
+function getHyperframesPackageSpecifier() {
+  return VERSION === "0.0.0-dev" ? "hyperframes" : `hyperframes@${VERSION}`;
+}
+function hyperframesScript(command2) {
+  return `npx --yes ${getHyperframesPackageSpecifier()} ${command2}`;
+}
+function buildPackageScripts() {
+  return {
+    dev: hyperframesScript("preview"),
+    check: `${hyperframesScript("lint")} && ${hyperframesScript("validate")} && ${hyperframesScript("inspect")}`,
+    render: hyperframesScript("render"),
+    publish: hyperframesScript("publish")
+  };
+}
+function writeDefaultPackageJson(destDir, projectName) {
+  const packageJsonPath = resolve22(destDir, "package.json");
+  if (existsSync38(packageJsonPath)) return;
+  writeFileSync18(
+    packageJsonPath,
+    `${JSON.stringify(
+      {
+        name: toPackageName(projectName),
+        private: true,
+        type: "module",
+        scripts: buildPackageScripts()
+      },
+      null,
+      2
+    )}
+`,
+    "utf-8"
+  );
+}
+function listHtmlFiles(dir) {
+  const files = [];
+  const ignoredDirs = /* @__PURE__ */ new Set([".git", "dist", "node_modules"]);
+  function walk(currentDir) {
+    for (const entry of readdirSync13(currentDir, { withFileTypes: true })) {
+      const entryPath = join40(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        if (!ignoredDirs.has(entry.name)) walk(entryPath);
+        continue;
+      }
+      if (entry.isFile() && entry.name.endsWith(".html")) {
+        files.push(entryPath);
+      }
+    }
+  }
+  walk(dir);
+  return files;
+}
+function injectTailwindBrowserScript(html) {
+  if (html.includes(TAILWIND_BROWSER_SRC)) return html;
+  const script = [
+    `<script>`,
+    `window.__tailwindReady=new Promise(function(resolve){`,
+    `var loaded=document.readyState==="complete";`,
+    `var resolved=false;`,
+    `var observer;`,
+    `function readTailwindCss(){var styles=document.querySelectorAll("style");for(var i=styles.length-1;i>=0;i--){var text=styles[i].textContent||"";if(text.indexOf("tailwindcss v")!==-1)return text;}return "";}`,
+    `function finish(){if(resolved||!loaded||!readTailwindCss())return;resolved=true;if(observer)observer.disconnect();resolve(true);}`,
+    `observer=new MutationObserver(finish);`,
+    `observer.observe(document.documentElement,{childList:true,subtree:true,characterData:true});`,
+    `if(loaded){finish();}else{window.addEventListener("load",function(){loaded=true;finish();},{once:true});}`,
+    `});`,
+    `</script>`,
+    `<script src="${TAILWIND_BROWSER_SRC}" integrity="${TAILWIND_BROWSER_INTEGRITY}" crossorigin="anonymous"></script>`
+  ].join("\n");
+  if (/<\/head>/i.test(html)) {
+    return html.replace(/<\/head>/i, (closingHead) => `
+${script}
+${closingHead}`);
+  }
+  return `${script}
+${html}`;
+}
+function writeTailwindSupport(destDir) {
+  for (const file of listHtmlFiles(destDir)) {
+    const html = readFileSync27(file, "utf-8");
+    writeFileSync18(file, injectTailwindBrowserScript(html), "utf-8");
+  }
+}
 function patchVideoSrc(dir, videoFilename, durationSeconds) {
   const htmlFiles = readdirSync13(dir, { withFileTypes: true, recursive: true }).filter((e2) => e2.isFile() && e2.name.endsWith(".html")).map((e2) => join40(e2.parentPath ?? e2.path, e2.name));
   for (const file of htmlFiles) {
@@ -37980,7 +38183,7 @@ async function handleVideoFile(videoPath, destDir, interactive) {
   }
   return { meta, localVideoName };
 }
-async function scaffoldProject(destDir, name, templateId, localVideoName, durationSeconds) {
+async function scaffoldProject(destDir, name, templateId, localVideoName, durationSeconds, tailwind = false) {
   mkdirSync23(destDir, { recursive: true });
   const templateDir = getStaticTemplateDir(templateId);
   if (existsSync38(templateDir)) {
@@ -37989,6 +38192,7 @@ async function scaffoldProject(destDir, name, templateId, localVideoName, durati
     await fetchRemoteTemplate(templateId, destDir);
   }
   patchVideoSrc(destDir, localVideoName, durationSeconds);
+  if (tailwind) writeTailwindSupport(destDir);
   writeFileSync18(
     resolve22(destDir, "meta.json"),
     JSON.stringify(
@@ -38006,6 +38210,7 @@ async function scaffoldProject(destDir, name, templateId, localVideoName, durati
     const { writeProjectConfig: writeProjectConfig2, DEFAULT_PROJECT_CONFIG: DEFAULT_PROJECT_CONFIG2 } = await Promise.resolve().then(() => (init_projectConfig(), projectConfig_exports));
     writeProjectConfig2(destDir, DEFAULT_PROJECT_CONFIG2);
   }
+  writeDefaultPackageJson(destDir, name);
   const sharedDir = getSharedTemplateDir();
   if (existsSync38(sharedDir)) {
     for (const entry of readdirSync13(sharedDir, { withFileTypes: true })) {
@@ -38017,7 +38222,7 @@ async function scaffoldProject(destDir, name, templateId, localVideoName, durati
     }
   }
 }
-var examples2, WEB_CODECS, DEFAULT_META, init_default;
+var examples2, WEB_CODECS, DEFAULT_META, TAILWIND_BROWSER_VERSION, TAILWIND_BROWSER_SRC, TAILWIND_BROWSER_INTEGRITY, init_default;
 var init_init = __esm({
   "src/commands/init.ts"() {
     "use strict";
@@ -38029,11 +38234,13 @@ var init_init = __esm({
     init_remote2();
     init_events();
     init_manager();
+    init_version();
     examples2 = [
       ["Create a project with the interactive wizard", "hyperframes init my-video"],
       ["Pick a starter example", "hyperframes init my-video --example warm-grain"],
       ["Start from an existing video file", "hyperframes init my-video --video clip.mp4"],
       ["Start from an audio file", "hyperframes init my-video --audio track.mp3"],
+      ["Scaffold with Tailwind CSS", "hyperframes init my-video --example blank --tailwind"],
       ["Non-interactive mode (for CI or AI agents)", "hyperframes init my-video --non-interactive"],
       ["Skip AI coding skills installation", "hyperframes init my-video --skip-skills"]
     ];
@@ -38046,6 +38253,9 @@ var init_init = __esm({
       hasAudio: false,
       videoCodec: "h264"
     };
+    TAILWIND_BROWSER_VERSION = "4.2.4";
+    TAILWIND_BROWSER_SRC = `https://cdn.jsdelivr.net/npm/@tailwindcss/browser@${TAILWIND_BROWSER_VERSION}/dist/index.global.js`;
+    TAILWIND_BROWSER_INTEGRITY = "sha384-v5YF9xS+gLRWdvrQ0u/WRbCkjSIH0NjHIPe8tBL1ZRrmI7PiSH6LLdzs0aAIMCuh";
     init_default = defineCommand({
       meta: {
         name: "init",
@@ -38098,6 +38308,10 @@ var init_init = __esm({
         "skip-skills": {
           type: "boolean",
           description: "Skip AI coding skills installation"
+        },
+        tailwind: {
+          type: "boolean",
+          description: "Add Tailwind CSS browser-runtime support"
         }
       },
       async run({ args }) {
@@ -38115,6 +38329,7 @@ var init_init = __esm({
         const audioFlag = args.audio;
         const skipTranscribe = args["skip-transcribe"] === true;
         const skipSkills = args["skip-skills"] === true;
+        const tailwind = args.tailwind === true;
         const nonInteractive = args["non-interactive"] === true;
         const modelFlag = args.model;
         const languageFlag = args.language;
@@ -38184,7 +38399,8 @@ var init_init = __esm({
               basename5(destDir2),
               templateId2,
               localVideoName2,
-              videoDuration2
+              videoDuration2,
+              tailwind
             );
           } catch (err) {
             console.error(
@@ -38195,7 +38411,7 @@ var init_init = __esm({
             console.error(c.dim("Use --example blank for offline use."));
             process.exit(1);
           }
-          trackInitTemplate(templateId2);
+          trackInitTemplate(templateId2, { tailwind });
           const transcriptFile2 = resolve22(destDir2, "transcript.json");
           if (existsSync38(transcriptFile2)) {
             await patchTranscript(destDir2, transcriptFile2);
@@ -38222,10 +38438,13 @@ var init_init = __esm({
           console.log(`     ${c.dim("More patterns: hyperframes.heygen.com/guides/prompting")}`);
           console.log();
           console.log(`  ${c.accent("4.")} Preview in the browser:`);
-          console.log(`     ${c.accent(`cd ${name2}`)} && ${c.accent("npx hyperframes preview")}`);
+          console.log(`     ${c.accent(`cd ${name2}`)} && ${c.accent("npm run dev")}`);
+          console.log();
+          console.log(`  ${c.accent("5.")} Check the composition:`);
+          console.log(`     ${c.accent(`cd ${name2}`)} && ${c.accent("npm run check")}`);
           console.log();
-          console.log(`  ${c.accent("5.")} Render to MP4 when ready:`);
-          console.log(`     ${c.accent(`cd ${name2}`)} && ${c.accent("npx hyperframes render")}`);
+          console.log(`  ${c.accent("6.")} Render to MP4 when ready:`);
+          console.log(`     ${c.accent(`cd ${name2}`)} && ${c.accent("npm run render")}`);
           console.log();
           console.log(`  ${c.dim("Full docs: hyperframes.heygen.com")}`);
           return;
@@ -38353,7 +38572,7 @@ var init_init = __esm({
           spin.start(`Downloading example ${c.accent(templateId)}...`);
         }
         try {
-          await scaffoldProject(destDir, name, templateId, localVideoName, videoDuration);
+          await scaffoldProject(destDir, name, templateId, localVideoName, videoDuration, tailwind);
           if (!isBundled) {
             spin.stop(c.success(`Downloaded ${templateId}`));
           }
@@ -38367,7 +38586,7 @@ ${c.dim("Use --example blank for offline use.")}`
           );
           process.exit(1);
         }
-        trackInitTemplate(templateId);
+        trackInitTemplate(templateId, { tailwind });
         const transcriptFile = resolve22(destDir, "transcript.json");
         if (existsSync38(transcriptFile)) {
           await patchTranscript(destDir, transcriptFile);

package/dist/skills/gsap/SKILL.md

@@ -5,6 +5,28 @@ description: GSAP animation reference for HyperFrames. Covers gsap.to(), from(),
 
 # GSAP
 
+## HyperFrames Contract
+
+HyperFrames controls GSAP through its `gsap` runtime adapter. Create a paused timeline synchronously, register it on `window.__timelines` with the exact `data-composition-id`, and let HyperFrames seek it.
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+<script>
+  window.__timelines = window.__timelines || {};
+  const tl = gsap.timeline({ paused: true });
+
+  tl.from(".title", { y: 48, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
+  tl.to(".accent", { scaleX: 1, duration: 0.5, ease: "power2.out" }, 0.25);
+
+  window.__timelines["main"] = tl; // key must equal data-composition-id on the composition root
+</script>
+```
+
+- The registry key must match the composition root's `data-composition-id`.
+- Do not call `tl.play()` for render-critical motion.
+- Do not build timelines inside async code, timers, or event handlers.
+- Keep loops finite. HyperFrames renders finite video durations.
+
 ## Core Tween Methods
 
 - **gsap.to(targets, vars)** — animate from current state to `vars`. Most common.
@@ -21,7 +43,7 @@ Always use **camelCase** property names (e.g. `backgroundColor`, `rotationX`).
 - **ease** — `"power1.out"` (default), `"power3.inOut"`, `"back.out(1.7)"`, `"elastic.out(1, 0.3)"`, `"none"`.
 - **stagger** — number `0.1` or object: `{ amount: 0.3, from: "center" }`, `{ each: 0.1, from: "random" }`.
 - **overwrite** — `false` (default), `true`, or `"auto"`.
-- **repeat** — number or `-1` for infinite. **yoyo** — alternates direction with repeat.
+- **repeat** — finite number; never `-1` in HyperFrames. Compute repeats from the visible duration. **yoyo** — alternates direction with repeat.
 - **onComplete**, **onStart**, **onUpdate** — callbacks.
 - **immediateRender** — default `true` for from()/fromTo(). Set `false` on later tweens targeting the same property+element to avoid overwrite.
 
@@ -209,3 +231,10 @@ Pause or kill off-screen animations.
 - Chain animations with delay when a timeline can sequence them.
 - Create tweens before the DOM exists.
 - Skip cleanup — always kill tweens when no longer needed.
+- Use infinite repeat values in HyperFrames compositions. Use finite repeat counts computed from the visible duration.
+
+## Credits And References
+
+- HyperFrames adapter source: `packages/core/src/runtime/adapters/gsap.ts`.
+- GSAP documentation: https://gsap.com/docs/v3/
+- GSAP timeline pause and seek behavior: https://gsap.com/docs/v3/GSAP/Timeline/pause%28%29/

package/dist/skills/hyperframes-cli/SKILL.md

@@ -25,6 +25,7 @@ npx hyperframes init my-video                        # interactive wizard
 npx hyperframes init my-video --example warm-grain   # pick an example
 npx hyperframes init my-video --video clip.mp4        # with video file
 npx hyperframes init my-video --audio track.mp3       # with audio file
+npx hyperframes init my-video --example blank --tailwind # with Tailwind v4 browser runtime
 npx hyperframes init my-video --non-interactive       # skip prompts (CI/agents)
 ```
 
@@ -32,6 +33,8 @@ Templates: `blank`, `warm-grain`, `play-mode`, `swiss-grid`, `vignelli`, `decisi
 
 `init` creates the right file structure, copies media, transcribes audio with Whisper, and installs AI coding skills. Use it instead of creating files by hand.
 
+When using `--tailwind`, invoke the `tailwind` skill before editing classes or theme tokens. The scaffold uses Tailwind v4.2 via the browser runtime, not Studio's Tailwind v3 setup.
+
 ## Linting
 
 ```bash

package/dist/templates/_shared/AGENTS.md

@@ -8,15 +8,15 @@ This project uses AI agent skills for framework-specific patterns. Install them
 npx skills add heygen-com/hyperframes
 ```
 
-Skills encode patterns like `window.__timelines` registration, `data-*` attribute semantics, and shader-compatible CSS rules that are not in generic web docs. Using them produces correct compositions from the start.
+Skills encode patterns like `window.__timelines` registration, `data-*` attribute semantics, Tailwind v4 browser-runtime styling for `--tailwind` projects, and shader-compatible CSS rules that are not in generic web docs. Using them produces correct compositions from the start.
 
 ## Commands
 
 ```bash
-npx hyperframes preview      # preview in browser (studio editor)
-npx hyperframes render       # render to MP4
-npx hyperframes lint         # validate compositions (errors + warnings)
-npx hyperframes lint --json  # machine-readable output for CI
+npm run dev          # preview in browser (studio editor)
+npm run check        # lint + validate + inspect
+npm run render       # render to MP4
+npm run publish      # publish and get a shareable link
 npx hyperframes docs <topic> # reference docs in terminal
 ```
 
@@ -30,10 +30,10 @@ npx hyperframes docs <topic> # reference docs in terminal
 
 ## Linting — Always Run After Changes
 
-After creating or editing any `.html` composition, run the linter before considering the task complete:
+After creating or editing any `.html` composition, run the full check before considering the task complete:
 
 ```bash
-npx hyperframes lint
+npm run check
 ```
 
 Fix all errors before presenting the result.

package/dist/templates/_shared/CLAUDE.md

@@ -10,7 +10,13 @@
 | **hyperframes-cli**        | `/hyperframes-cli`        | CLI commands: init, lint, preview, render, transcribe, tts                                        |
 | **hyperframes-registry**   | `/hyperframes-registry`   | Installing blocks and components via `hyperframes add`                                            |
 | **website-to-hyperframes** | `/website-to-hyperframes` | Capturing a URL and turning it into a video — full website-to-video pipeline                      |
+| **tailwind**               | `/tailwind`               | Tailwind v4 browser-runtime styles for projects created with `hyperframes init --tailwind`        |
 | **gsap**                   | `/gsap`                   | GSAP animations for HyperFrames — tweens, timelines, easing, performance                          |
+| **animejs**                | `/animejs`                | Anime.js animations registered on `window.__hfAnime`                                              |
+| **css-animations**         | `/css-animations`         | CSS keyframes that HyperFrames can pause and seek                                                 |
+| **lottie**                 | `/lottie`                 | `lottie-web` and dotLottie players registered on `window.__hfLottie`                              |
+| **three**                  | `/three`                  | Three.js scenes rendered from HyperFrames `hf-seek` events                                        |
+| **waapi**                  | `/waapi`                  | Web Animations API motion driven through `document.getAnimations()`                               |
 
 > **Skills not available?** Ask the user to run `npx hyperframes skills` and restart their
 > agent session, or install manually: `npx skills add heygen-com/hyperframes`.
@@ -18,9 +24,10 @@
 ## Commands
 
 ```bash
-npx hyperframes preview          # preview in browser (studio editor)
-npx hyperframes render       # render to MP4
-npx hyperframes lint         # validate compositions (errors + warnings)
+npm run dev          # preview in browser (studio editor)
+npm run check        # lint + validate + inspect
+npm run render       # render to MP4
+npm run publish      # publish and get a shareable link
 npx hyperframes lint --verbose  # include info-level findings
 npx hyperframes lint --json     # machine-readable output for CI
 npx hyperframes docs <topic> # reference docs in terminal
@@ -51,13 +58,13 @@ https://hyperframes.heygen.com/llms.txt
 
 ## Linting — ALWAYS RUN AFTER CHANGES
 
-After creating or editing any `.html` composition, **always** run the linter before considering the task complete:
+After creating or editing any `.html` composition, **always** run the full check before considering the task complete:
 
 ```bash
-npx hyperframes lint
+npm run check
 ```
 
-Fix all errors before presenting the result. Warnings are informational and usually safe to ignore.
+Fix all errors before presenting the result. Inspect warnings should be reviewed before rendering.
 
 ## Key Rules
 

package/package.json

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