studioflow 0.1.4 → 0.2.0

package/dist/index.js

@@ -6,9 +6,9 @@ var __export = (target, all) => {
 };
 
 // src/index.ts
-import fs12 from "node:fs/promises";
+import fs13 from "node:fs/promises";
 import path13 from "node:path";
-import { fileURLToPath as fileURLToPath3 } from "node:url";
+import { fileURLToPath as fileURLToPath4 } from "node:url";
 
 // ../../node_modules/.pnpm/kleur@4.1.5/node_modules/kleur/index.mjs
 var FORCE_COLOR;
@@ -187,7 +187,9 @@ async function startBrowser(baseUrl, opts = {}) {
 }
 
 // ../../packages/adapters-playwright/src/actions.ts
+import fs2 from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 
 // ../../packages/adapters-playwright/src/assertions.ts
 async function assertText(page, text, timeoutMs = 5e3) {
@@ -216,9 +218,105 @@ function intEnv(name, fallback, env = process.env) {
   return Number.isFinite(parsed) ? parsed : fallback;
 }
 var maxDelayMs = 6e4;
+var moduleDir = path.dirname(fileURLToPath(import.meta.url));
+var macosCursorSvgDataUri = "data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%2226%22%20height%3D%2236%22%20viewBox%3D%220%200%2026%2036%22%3E%3Cpath%20d%3D%22M2%201.5v26.2l6.7-6.4%204.4%2012.8%204.2-1.6-4.4-12.8h10.8L2%201.5z%22%20fill%3D%22%23111%22%2F%3E%3Cpath%20d%3D%22M4%204.5v18.1l5.1-4.9a1%201%200%200%201%201.6.4l3.7%2010.9%201.4-.5-3.7-10.9a1%201%200%200%201%20.9-1.3h7.8L4%204.5z%22%20fill%3D%22%23fff%22%2F%3E%3C%2Fsvg%3E";
+var genericCursorSvgDataUri = "data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%2222%22%20height%3D%2230%22%20viewBox%3D%220%200%2022%2030%22%3E%3Cpath%20d%3D%22M1.5%201.5V22.2L7.4%2017.4L11%2028.5L14.4%2027L10.8%2015.9H19.6L1.5%201.5Z%22%20fill%3D%22white%22%20stroke%3D%22%23000%22%20stroke-width%3D%221.5%22%20stroke-linejoin%3D%22round%22%2F%3E%3C%2Fsvg%3E";
+var macosFallbackCursorAsset = {
+  dataUri: macosCursorSvgDataUri,
+  width: 26,
+  height: 36,
+  hotspotX: 2,
+  hotspotY: 1
+};
+var genericCursorAsset = {
+  dataUri: genericCursorSvgDataUri,
+  width: 22,
+  height: 30,
+  hotspotX: 2,
+  hotspotY: 1
+};
+var cursorAssetCache = /* @__PURE__ */ new Map();
+function cursorThemeEnv(env = process.env) {
+  const raw = env.STUDIOFLOW_CURSOR_THEME?.trim().toLowerCase();
+  if (raw === "generic") return "generic";
+  return "macos";
+}
+function parsePngDimensions(buffer) {
+  if (buffer.length < 24) return null;
+  const pngHeader = [137, 80, 78, 71, 13, 10, 26, 10];
+  for (let index = 0; index < pngHeader.length; index += 1) {
+    if (buffer[index] !== pngHeader[index]) {
+      return null;
+    }
+  }
+  const width = buffer.readUInt32BE(16);
+  const height = buffer.readUInt32BE(20);
+  if (width <= 0 || height <= 0) return null;
+  return { width, height };
+}
+function resolveCursorPngPath(env = process.env) {
+  const projectRoot = env.INIT_CWD ?? process.cwd();
+  const explicitPath = env.STUDIOFLOW_CURSOR_PNG_PATH?.trim();
+  const candidates = [
+    explicitPath ? path.isAbsolute(explicitPath) ? explicitPath : path.resolve(projectRoot, explicitPath) : "",
+    path.resolve(projectRoot, "apps/cli/assets/cursor.png"),
+    path.resolve(projectRoot, "apps/cli/cursor.png"),
+    path.resolve(projectRoot, "assets/cursor.png"),
+    path.resolve(projectRoot, "cursor.png"),
+    path.resolve(moduleDir, "../../../apps/cli/assets/cursor.png"),
+    path.resolve(moduleDir, "../../../apps/cli/cursor.png"),
+    path.resolve(moduleDir, "../assets/cursor.png"),
+    path.resolve(moduleDir, "../cursor.png")
+  ];
+  const visited = /* @__PURE__ */ new Set();
+  for (const candidate of candidates) {
+    if (!candidate || visited.has(candidate)) continue;
+    visited.add(candidate);
+    if (fs2.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+function loadCursorPngAsset(filePath, env = process.env) {
+  const cached = cursorAssetCache.get(filePath);
+  if (cached) return cached;
+  try {
+    const image = fs2.readFileSync(filePath);
+    const dimensions = parsePngDimensions(image);
+    const maxEdge = Math.max(20, intEnv("STUDIOFLOW_CURSOR_MAX_EDGE_PX", 34, env));
+    const sourceWidth = dimensions?.width ?? 26;
+    const sourceHeight = dimensions?.height ?? 36;
+    const scale = maxEdge / Math.max(sourceWidth, sourceHeight);
+    const width = Math.max(18, Math.round(sourceWidth * scale));
+    const height = Math.max(18, Math.round(sourceHeight * scale));
+    const asset = {
+      dataUri: `data:image/png;base64,${image.toString("base64")}`,
+      width,
+      height,
+      hotspotX: Math.max(1, Math.round(width * 0.08)),
+      hotspotY: Math.max(1, Math.round(height * 0.08))
+    };
+    cursorAssetCache.set(filePath, asset);
+    return asset;
+  } catch {
+    return null;
+  }
+}
+function resolveCursorOverlayAsset(theme, env = process.env) {
+  if (theme === "generic") {
+    return genericCursorAsset;
+  }
+  const cursorPngPath = resolveCursorPngPath(env);
+  if (!cursorPngPath) {
+    return macosFallbackCursorAsset;
+  }
+  return loadCursorPngAsset(cursorPngPath, env) ?? macosFallbackCursorAsset;
+}
 function resolveRuntimePacingDefaults(env = process.env) {
   return {
     renderCursorOverlay: boolEnv("STUDIOFLOW_RENDER_CURSOR", true, env),
+    cursorTheme: cursorThemeEnv(env),
     cursorMoveMs: Math.max(0, intEnv("STUDIOFLOW_CURSOR_MOVE_MS", 430, env)),
     cursorHighlightMs: Math.max(0, intEnv("STUDIOFLOW_CURSOR_HIGHLIGHT_MS", 170, env)),
     realisticTyping: boolEnv("STUDIOFLOW_REALISTIC_TYPING", true, env),
@@ -231,9 +329,132 @@ function resolveRuntimePacingDefaults(env = process.env) {
     pacingJitterEnabled: boolEnv("STUDIOFLOW_PACING_JITTER", true, env)
   };
 }
-var cursorOverlaySetupScript = (clickPulseMs) => `
+var defaultScrollPlan = {
+  required: false,
+  alignment: "center",
+  maxAttempts: 2
+};
+async function collectTargetSnapshot(page, target) {
+  const locator = page.locator(target).first();
+  try {
+    if (await locator.count() === 0) {
+      return {
+        exists: false,
+        visible: false,
+        inViewport: false,
+        clippedByOverflow: false,
+        scrollableAncestors: 0
+      };
+    }
+    return locator.evaluate((element) => {
+      const rect = element.getBoundingClientRect();
+      const style = window.getComputedStyle(element);
+      const viewport = {
+        width: window.innerWidth,
+        height: window.innerHeight
+      };
+      const visible = style.display !== "none" && style.visibility !== "hidden" && Number(style.opacity || "1") > 0 && rect.width > 0 && rect.height > 0;
+      const inViewport = rect.bottom > 0 && rect.right > 0 && rect.top < viewport.height && rect.left < viewport.width;
+      let clippedByOverflow = false;
+      let scrollableAncestors = 0;
+      let parent = element.parentElement;
+      while (parent) {
+        const parentStyle = window.getComputedStyle(parent);
+        const scrollableY = /(auto|scroll|overlay)/.test(parentStyle.overflowY) && parent.scrollHeight > parent.clientHeight + 1;
+        const scrollableX = /(auto|scroll|overlay)/.test(parentStyle.overflowX) && parent.scrollWidth > parent.clientWidth + 1;
+        if (scrollableY || scrollableX) {
+          scrollableAncestors += 1;
+          const parentRect = parent.getBoundingClientRect();
+          if (rect.top < parentRect.top || rect.bottom > parentRect.bottom || rect.left < parentRect.left || rect.right > parentRect.right) {
+            clippedByOverflow = true;
+          }
+        }
+        parent = parent.parentElement;
+      }
+      return {
+        exists: true,
+        visible,
+        inViewport,
+        clippedByOverflow,
+        scrollableAncestors,
+        rect: {
+          top: Math.round(rect.top),
+          left: Math.round(rect.left),
+          width: Math.round(rect.width),
+          height: Math.round(rect.height)
+        },
+        viewport
+      };
+    });
+  } catch {
+    return {
+      exists: false,
+      visible: false,
+      inViewport: false,
+      clippedByOverflow: false,
+      scrollableAncestors: 0
+    };
+  }
+}
+async function scrollTargetIntoView(page, target, timeoutMs, runtime) {
+  const locator = page.locator(target).first();
+  const snapshot = await collectTargetSnapshot(page, target);
+  if (!snapshot.exists) return;
+  const effective = defaultScrollPlan;
+  const needsScroll = snapshot.visible && (!snapshot.inViewport || snapshot.clippedByOverflow);
+  if (!effective.required && !needsScroll) return;
+  for (let attempt = 0; attempt < effective.maxAttempts; attempt += 1) {
+    try {
+      await locator.evaluate(
+        (element, alignment) => {
+          const block = alignment === "start" || alignment === "center" || alignment === "end" ? alignment : "nearest";
+          let parent = element.parentElement;
+          while (parent) {
+            const style = window.getComputedStyle(parent);
+            const scrollableY = /(auto|scroll|overlay)/.test(style.overflowY) && parent.scrollHeight > parent.clientHeight + 1;
+            const scrollableX = /(auto|scroll|overlay)/.test(style.overflowX) && parent.scrollWidth > parent.clientWidth + 1;
+            if (scrollableY || scrollableX) {
+              const targetRect = element.getBoundingClientRect();
+              const parentRect = parent.getBoundingClientRect();
+              if (scrollableY) {
+                const offsetTop = targetRect.top - parentRect.top + parent.scrollTop;
+                if (block === "start") {
+                  parent.scrollTop = offsetTop - 8;
+                } else if (block === "end") {
+                  parent.scrollTop = offsetTop - parent.clientHeight + targetRect.height + 8;
+                } else if (block === "center") {
+                  parent.scrollTop = offsetTop - parent.clientHeight / 2 + targetRect.height / 2;
+                } else if (targetRect.top < parentRect.top || targetRect.bottom > parentRect.bottom) {
+                  parent.scrollTop = offsetTop - parent.clientHeight / 2 + targetRect.height / 2;
+                }
+              }
+              if (scrollableX) {
+                const offsetLeft = targetRect.left - parentRect.left + parent.scrollLeft;
+                parent.scrollLeft = offsetLeft - parent.clientWidth / 2 + targetRect.width / 2;
+              }
+            }
+            parent = parent.parentElement;
+          }
+          element.scrollIntoView({ behavior: "instant", block, inline: "nearest" });
+        },
+        effective.alignment
+      );
+    } catch {
+      return;
+    }
+    const settleMs = Math.min(timeoutMs, Math.max(40, Math.round(runtime.stepPreDelayMs * 0.5)));
+    if (settleMs > 0) {
+      await wait(settleMs);
+    }
+    const after = await collectTargetSnapshot(page, target);
+    if (!after.exists) return;
+    if (after.visible && after.inViewport && !after.clippedByOverflow) return;
+  }
+}
+var cursorOverlaySetupScript = (clickPulseMs, theme, asset) => `
 (() => {
   const win = window;
+  const cursorAsset = "${asset.dataUri}";
   if (win.__studioflowCursor) return;
 
   if (!document.getElementById("studioflow-cursor-style")) {
@@ -244,32 +465,33 @@ var cursorOverlaySetupScript = (clickPulseMs) => `
         position: fixed;
         top: 0;
         left: 0;
-        width: 22px;
-        height: 30px;
-        background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='22' height='30' viewBox='0 0 22 30'%3E%3Cpath d='M1.5 1.5V22.2L7.4 17.4L11 28.5L14.4 27L10.8 15.9H19.6L1.5 1.5Z' fill='white' stroke='%23000' stroke-width='1.5' stroke-linejoin='round'/%3E%3C/svg%3E");
+        width: ${asset.width}px;
+        height: ${asset.height}px;
+        background-image: url("\${cursorAsset}");
         background-repeat: no-repeat;
-        background-size: 22px 30px;
+        background-size: ${asset.width}px ${asset.height}px;
         pointer-events: none;
         z-index: 2147483647;
-        filter: drop-shadow(0 1px 1px rgba(0, 0, 0, 0.55));
-        transform: translate3d(16px, 16px, 0);
-        transition-property: transform;
-        transition-timing-function: cubic-bezier(0.22, 1, 0.36, 1);
+        opacity: 0;
+        transform: translate3d(-9999px, -9999px, 0);
+        filter: drop-shadow(0 1px 2px rgba(0, 0, 0, 0.48));
+        transition: opacity 120ms ease;
+        will-change: transform;
       }
       #studioflow-cursor::after {
         content: "";
         position: absolute;
-        left: -8px;
-        top: -8px;
-        width: 20px;
-        height: 20px;
+        left: -7px;
+        top: -7px;
+        width: 18px;
+        height: 18px;
         border-radius: 999px;
-        border: 2px solid rgba(59, 130, 246, 0.72);
+        border: 2px solid rgba(37, 99, 235, 0.72);
         opacity: 0;
         transform: scale(0.65);
       }
       #studioflow-cursor.studioflow-cursor-pulse::after {
-        animation: studioflow-cursor-pulse ${Math.max(0, clickPulseMs)}ms ease-out;
+        animation: studioflow-cursor-pulse var(--studioflow-click-pulse-ms, ${Math.max(0, clickPulseMs)}ms) ease-out;
       }
       @keyframes studioflow-cursor-pulse {
         0% { opacity: 0.9; transform: scale(0.55); }
@@ -282,20 +504,94 @@ var cursorOverlaySetupScript = (clickPulseMs) => `
   const cursor = document.createElement("div");
   cursor.id = "studioflow-cursor";
   cursor.setAttribute("aria-hidden", "true");
+  cursor.dataset.theme = "${theme}";
   document.body.appendChild(cursor);
 
-  let x = 16;
-  let y = 16;
-  const setPosition = (nextX, nextY, durationMs) => {
+  const hotSpotX = ${asset.hotspotX};
+  const hotSpotY = ${asset.hotspotY};
+  let x = 0;
+  let y = 0;
+  let initialized = false;
+  let raf = 0;
+  let activeResolve = null;
+
+  const resolveActiveAnimation = () => {
+    if (activeResolve) {
+      const done = activeResolve;
+      activeResolve = null;
+      done();
+    }
+  };
+
+  const stopAnimation = () => {
+    if (raf) {
+      cancelAnimationFrame(raf);
+      raf = 0;
+    }
+    resolveActiveAnimation();
+  };
+
+  const setPosition = (nextX, nextY) => {
     x = nextX;
     y = nextY;
-    cursor.style.transitionDuration = \`\${Math.max(0, durationMs)}ms\`;
-    cursor.style.transform = \`translate3d(\${x}px, \${y}px, 0)\`;
+    cursor.style.transform = \`translate3d(\${Math.round(x - hotSpotX)}px, \${Math.round(y - hotSpotY)}px, 0)\`;
+  };
+
+  const easeInOut = (value) => {
+    if (value <= 0) return 0;
+    if (value >= 1) return 1;
+    return value < 0.5 ? 2 * value * value : 1 - Math.pow(-2 * value + 2, 2) / 2;
+  };
+
+  const animateTo = (nextX, nextY, durationMs) => {
+    const startX = x;
+    const startY = y;
+    const ms = Math.max(0, Math.round(durationMs));
+
+    if (ms === 0 || (Math.abs(startX - nextX) < 0.5 && Math.abs(startY - nextY) < 0.5)) {
+      setPosition(nextX, nextY);
+      return Promise.resolve();
+    }
+
+    return new Promise((resolve) => {
+      activeResolve = resolve;
+      const start = performance.now();
+      const tick = (now) => {
+        const progress = Math.min(1, (now - start) / ms);
+        const eased = easeInOut(progress);
+        const currentX = startX + (nextX - startX) * eased;
+        const currentY = startY + (nextY - startY) * eased;
+        setPosition(currentX, currentY);
+        if (progress >= 1) {
+          raf = 0;
+          resolveActiveAnimation();
+          return;
+        }
+        raf = requestAnimationFrame(tick);
+      };
+      raf = requestAnimationFrame(tick);
+    });
   };
 
   win.__studioflowCursor = {
     moveTo(nextX, nextY, durationMs) {
-      setPosition(nextX, nextY, durationMs);
+      const targetX = Number(nextX) || 0;
+      const targetY = Number(nextY) || 0;
+      const transitionMs = Math.max(0, Number(durationMs) || 0);
+      stopAnimation();
+
+      if (!initialized) {
+        initialized = true;
+        cursor.style.opacity = "1";
+        setPosition(targetX - 14, targetY - 10);
+        return animateTo(targetX, targetY, Math.min(280, Math.max(120, transitionMs)));
+      }
+
+      return animateTo(targetX, targetY, transitionMs);
+    },
+    getPosition() {
+      if (!initialized) return null;
+      return { x, y };
     },
     clickPulse() {
       cursor.classList.remove("studioflow-cursor-pulse");
@@ -308,15 +604,32 @@ var cursorOverlaySetupScript = (clickPulseMs) => `
 var cursorMoveScript = (point, durationMs) => `
 (() => {
   const cursor = window.__studioflowCursor;
-  if (cursor) cursor.moveTo(${point.x}, ${point.y}, ${durationMs});
+  if (cursor) return cursor.moveTo(${point.x}, ${point.y}, ${durationMs});
+  return undefined;
+})();
+`;
+var cursorClickPulseScript = (pulseMs) => `
+(() => {
+  const cursor = window.__studioflowCursor;
+  if (!cursor) return;
+  const pulse = Math.max(0, Math.round(${pulseMs}));
+  const cursorNode = document.getElementById("studioflow-cursor");
+  if (cursorNode) {
+    cursorNode.style.setProperty("--studioflow-click-pulse-ms", pulse + "ms");
+  }
+  cursor.clickPulse();
 })();
 `;
-var cursorClickPulseScript = `
+var cursorPositionScript = `
 (() => {
   const cursor = window.__studioflowCursor;
-  if (cursor) cursor.clickPulse();
+  if (!cursor) return null;
+  return cursor.getPosition();
 })();
 `;
+var cursorExistsScript = `
+(() => Boolean(window.__studioflowCursor))();
+`;
 function hashString(input) {
   let hash = 2166136261;
   for (let i = 0; i < input.length; i += 1) {
@@ -350,7 +663,29 @@ function sanitizeScreenshotName(raw) {
 }
 async function ensureCursorOverlay(page, runtime) {
   if (!runtime.renderCursorOverlay) return;
-  await page.evaluate(cursorOverlaySetupScript(runtime.clickPulseMs));
+  const cursorExists = await page.evaluate(cursorExistsScript);
+  if (cursorExists) return;
+  const cursorAsset = resolveCursorOverlayAsset(runtime.cursorTheme);
+  await page.evaluate(cursorOverlaySetupScript(runtime.clickPulseMs, runtime.cursorTheme, cursorAsset));
+}
+function distanceBetweenPoints(start, end) {
+  return Math.hypot(end.x - start.x, end.y - start.y);
+}
+function resolveCursorTravelDuration(baseMs, start, end) {
+  if (baseMs <= 0) return 0;
+  if (!start) {
+    return Math.max(120, Math.round(baseMs * 0.7));
+  }
+  const distanceMs = distanceBetweenPoints(start, end) * 1.1;
+  const blended = baseMs * 0.45 + distanceMs * 0.55;
+  const minMs = Math.max(110, Math.round(baseMs * 0.35));
+  const maxMs = Math.min(maxDelayMs, Math.max(850, Math.round(baseMs * 2.2)));
+  return Math.max(minMs, Math.min(maxMs, Math.round(blended)));
+}
+async function getCursorPosition(page, runtime) {
+  if (!runtime.renderCursorOverlay) return null;
+  await ensureCursorOverlay(page, runtime);
+  return page.evaluate(cursorPositionScript);
 }
 async function getTargetCenter(page, target) {
   const box = await page.locator(target).first().boundingBox();
@@ -362,23 +697,30 @@ async function moveCursor(page, point, durationMs, runtime) {
   if (runtime.renderCursorOverlay) {
     await ensureCursorOverlay(page, runtime);
     await page.evaluate(cursorMoveScript(point, durationMs));
+    return;
+  }
+  if (durationMs > 0) {
+    await wait(durationMs);
   }
 }
-async function clickPulse(page, runtime) {
+async function clickPulse(page, runtime, pulseMs) {
   if (!runtime.renderCursorOverlay) return;
   await ensureCursorOverlay(page, runtime);
-  await page.evaluate(cursorClickPulseScript);
+  await page.evaluate(cursorClickPulseScript(pulseMs));
 }
-async function applyPreStepPacing(page, step, context, runtime) {
+async function applyPreStepPacing(page, step, timeout, context, runtime) {
   const preDelay = resolvePacedDelay(step.preDelayMs ?? runtime.stepPreDelayMs, context, runtime, "pre");
   if (preDelay > 0) {
     await wait(preDelay);
   }
   const shouldMoveCursor = ["click", "type"].includes(step.action) && Boolean(step.target);
   if (!shouldMoveCursor || !step.target) return;
+  await scrollTargetIntoView(page, step.target, timeout, runtime);
   const center = await getTargetCenter(page, step.target);
   if (!center) return;
-  const moveMs = resolvePacedDelay(step.mouseMoveMs ?? runtime.cursorMoveMs, context, runtime, "move");
+  const baseMoveMs = resolvePacedDelay(step.mouseMoveMs ?? runtime.cursorMoveMs, context, runtime, "move");
+  const currentCursorPosition = await getCursorPosition(page, runtime);
+  const moveMs = resolveCursorTravelDuration(baseMoveMs, currentCursorPosition, center);
   if (moveMs > 0) {
     await moveCursor(page, center, moveMs, runtime);
   }
@@ -400,7 +742,7 @@ async function applyPostStepPacing(step, context, runtime) {
 async function executeStep(page, step, runDir, baseUrl, context = {}) {
   const timeout = step.timeoutMs ?? 6e3;
   const runtime = resolveRuntimePacingDefaults();
-  await applyPreStepPacing(page, step, context, runtime);
+  await applyPreStepPacing(page, step, timeout, context, runtime);
   if (step.action === "goto") {
     const target = step.value ?? "/";
     const isAbsolute = /^https?:\/\//.test(target);
@@ -410,17 +752,21 @@ async function executeStep(page, step, runDir, baseUrl, context = {}) {
   }
   if (step.action === "click") {
     if (!step.target) throw new Error(`Step ${step.id} missing target`);
+    await scrollTargetIntoView(page, step.target, timeout, runtime);
     await page.locator(step.target).first().click({ timeout });
-    await clickPulse(page, runtime);
+    const pulseMs = resolvePacedDelay(runtime.clickPulseMs, context, runtime, "click", false);
+    await clickPulse(page, runtime, pulseMs);
     await applyPostStepPacing(step, context, runtime);
     return;
   }
   if (step.action === "type") {
     if (!step.target) throw new Error(`Step ${step.id} missing target`);
+    await scrollTargetIntoView(page, step.target, timeout, runtime);
     const locator = page.locator(step.target).first();
     if (runtime.realisticTyping) {
       await locator.click({ timeout });
-      await clickPulse(page, runtime);
+      const pulseMs = resolvePacedDelay(runtime.clickPulseMs, context, runtime, "click", false);
+      await clickPulse(page, runtime, pulseMs);
       await locator.fill("", { timeout });
       const effectiveTypingDelay = resolvePacedDelay(runtime.typingDelayMs, context, runtime, "typing", false);
       await page.keyboard.type(step.value ?? "", { delay: effectiveTypingDelay });
@@ -432,6 +778,7 @@ async function executeStep(page, step, runDir, baseUrl, context = {}) {
   }
   if (step.action === "wait_for") {
     if (step.target) {
+      await scrollTargetIntoView(page, step.target, timeout, runtime);
       await page.locator(step.target).first().waitFor({ state: "visible", timeout });
       await applyPostStepPacing(step, context, runtime);
       return;
@@ -451,6 +798,7 @@ async function executeStep(page, step, runDir, baseUrl, context = {}) {
   }
   if (step.action === "assert_visible") {
     if (!step.target) throw new Error(`Step ${step.id} missing target`);
+    await scrollTargetIntoView(page, step.target, timeout, runtime);
     await assertVisible(page, step.target, timeout);
     await applyPostStepPacing(step, context, runtime);
     return;
@@ -470,10 +818,10 @@ async function executeStep(page, step, runDir, baseUrl, context = {}) {
 }
 
 // ../../packages/flow-registry/src/index.ts
-import fs2 from "node:fs/promises";
+import fs3 from "node:fs/promises";
 import os from "node:os";
 import path2 from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
 import YAML from "yaml";
 
 // ../../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/external.js
@@ -4635,10 +4983,20 @@ var runArtifactIndexSchema = external_exports.object({
 });
 
 // ../../packages/flow-registry/src/index.ts
-var __filename = fileURLToPath(import.meta.url);
+var __filename = fileURLToPath2(import.meta.url);
 var __dirname = path2.dirname(__filename);
 var rootDir = path2.resolve(__dirname, "..");
-var builtInFlowsDir = path2.join(rootDir, "flows");
+function builtInFlowsDirs() {
+  const configured = process.env.STUDIOFLOW_FLOWS_SOURCE?.trim();
+  const candidates = [
+    configured ? path2.resolve(configured) : "",
+    path2.join(rootDir, "bundled", "flows"),
+    path2.join(rootDir, "flows"),
+    path2.resolve(rootDir, "../../packages/flow-registry/flows"),
+    path2.resolve(process.cwd(), "packages/flow-registry/flows")
+  ].filter((value) => Boolean(value));
+  return Array.from(new Set(candidates));
+}
 function dataRoot() {
   const configured = process.env.STUDIOFLOW_DATA_DIR ?? process.env.STUDIOFLOW_HOME;
   if (configured && configured.trim()) {
@@ -4651,7 +5009,7 @@ function userFlowsDir() {
 }
 async function listFlowFiles(dir) {
   try {
-    const files = await fs2.readdir(dir);
+    const files = await fs3.readdir(dir);
     return files.filter((f) => [".yaml", ".yml", ".json"].includes(path2.extname(f).toLowerCase()));
   } catch (error) {
     const code = error.code;
@@ -4668,12 +5026,12 @@ async function loadFlowFromFile(filePath) {
   if (![".yaml", ".yml", ".json"].includes(ext)) {
     throw new Error(`Unsupported flow file format: ${filePath}`);
   }
-  const raw = await fs2.readFile(filePath, "utf8");
+  const raw = await fs3.readFile(filePath, "utf8");
   return parseFlow(raw, ext);
 }
 async function loadFlows() {
   const merged = /* @__PURE__ */ new Map();
-  const dirs = [builtInFlowsDir, userFlowsDir()];
+  const dirs = [...builtInFlowsDirs(), userFlowsDir()];
   for (const dir of dirs) {
     const files = await listFlowFiles(dir);
     for (const file of files) {
@@ -4686,7 +5044,7 @@ async function loadFlows() {
 }
 
 // ../../packages/orchestrator/src/engine.ts
-import fs6 from "node:fs/promises";
+import fs7 from "node:fs/promises";
 import path5 from "node:path";
 
 // ../../packages/artifacts/src/paths.ts
@@ -4710,23 +5068,23 @@ function getRunDir(runId) {
 }
 
 // ../../packages/artifacts/src/logger.ts
-import fs3 from "node:fs/promises";
+import fs4 from "node:fs/promises";
 async function appendJsonLine(filePath, payload) {
-  await fs3.appendFile(filePath, `${JSON.stringify(payload)}
+  await fs4.appendFile(filePath, `${JSON.stringify(payload)}
 `, "utf8");
 }
 
 // ../../packages/artifacts/src/writer.ts
-import fs4 from "node:fs/promises";
+import fs5 from "node:fs/promises";
 import path4 from "node:path";
 async function createRunContext() {
   const now = /* @__PURE__ */ new Date();
   const runId = now.toISOString().replace(/[:.]/g, "-");
   const runDir = getRunDir(runId);
   const screenshotsDir = path4.join(runDir, "screenshots");
-  await fs4.mkdir(screenshotsDir, { recursive: true });
+  await fs5.mkdir(screenshotsDir, { recursive: true });
   const eventsFile = path4.join(runDir, "events.jsonl");
-  await fs4.writeFile(eventsFile, "", "utf8");
+  await fs5.writeFile(eventsFile, "", "utf8");
   return {
     runId,
     runDir,
@@ -4735,7 +5093,7 @@ async function createRunContext() {
   };
 }
 async function writeJsonFile(filePath, payload) {
-  await fs4.writeFile(filePath, JSON.stringify(payload, null, 2), "utf8");
+  await fs5.writeFile(filePath, JSON.stringify(payload, null, 2), "utf8");
 }
 
 // ../../packages/adapters-desktop/src/osascript.ts
@@ -4749,14 +5107,14 @@ async function runAppleScript(script) {
 
 // ../../packages/adapters-desktop/src/permissions.ts
 import { execFile as execFile2 } from "node:child_process";
-import fs5 from "node:fs/promises";
+import fs6 from "node:fs/promises";
 import { promisify as promisify2 } from "node:util";
 var execFileAsync2 = promisify2(execFile2);
 async function checkPermissions() {
   const notes = [];
   let screenStudioInstalled = false;
   try {
-    await fs5.access("/Applications/Screen Studio.app");
+    await fs6.access("/Applications/Screen Studio.app");
     screenStudioInstalled = true;
   } catch {
     notes.push("Screen Studio app not found at /Applications/Screen Studio.app");
@@ -4833,27 +5191,46 @@ async function ensureAutomationPermissions() {
   );
 }
 
-// ../../packages/adapters-screenstudio/src/menu-controls.ts
+// ../../packages/adapters-desktop/src/quicktime.ts
+var defaultQuickTimeAppName = process.env.QUICKTIME_APP_NAME ?? "QuickTime Player";
+function int(value, fallback) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+var preConfirmDelay = int(process.env.QUICKTIME_PRE_CONFIRM_DELAY_MS, 700);
+var postStartDelay = int(process.env.QUICKTIME_POST_START_DELAY_MS, 1200);
+var postStopDelay = int(process.env.QUICKTIME_POST_STOP_DELAY_MS, 900);
+var exportDialogConfirmDelay = int(process.env.QUICKTIME_EXPORT_DIALOG_CONFIRM_DELAY_MS, 900);
+var exportDelay = int(process.env.QUICKTIME_EXPORT_DELAY_MS, 2500);
 function quote(value) {
   return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
 }
 function normalizeMenuItem(raw) {
   return raw.trim();
 }
-function parseMenuItems(stdout) {
+function parseQuickTimeMenuItems(stdout) {
   if (!stdout.trim()) {
     return [];
   }
   return stdout.split(",").map(normalizeMenuItem).filter((item) => item.length > 0 && item !== "missing value");
 }
-function buildActivateScreenStudioScript(appName2) {
+function buildActivateQuickTimeScript(appName2) {
   return `tell application "${quote(appName2)}" to activate`;
 }
-function buildListRecordMenuItemsScript(appName2) {
-  return `tell application "System Events" to tell process "${quote(appName2)}" to get name of every menu item of menu "Record" of menu bar 1`;
+function buildListQuickTimeFileMenuItemsScript(appName2) {
+  return `tell application "System Events" to tell process "${quote(appName2)}" to get name of every menu item of menu "File" of menu bar 1`;
 }
-function buildClickRecordMenuItemScript(appName2, itemName) {
-  return `tell application "System Events" to tell process "${quote(appName2)}" to click menu item "${quote(itemName)}" of menu "Record" of menu bar 1`;
+function buildClickQuickTimeFileMenuItemScript(appName2, itemName) {
+  return `tell application "System Events" to tell process "${quote(appName2)}" to click menu item "${quote(itemName)}" of menu "File" of menu bar 1`;
+}
+function buildQuickTimeStartShortcutScript() {
+  return 'tell application "System Events" to keystroke "n" using {command down, control down}';
+}
+function buildQuickTimeStopShortcutScript() {
+  return 'tell application "System Events" to key code 53 using {command down, control down}';
+}
+function buildQuickTimeSaveShortcutScript() {
+  return 'tell application "System Events" to keystroke "s" using {command down}';
 }
 function buildPressReturnScript() {
   return 'tell application "System Events" to key code 36';
@@ -4861,6 +5238,105 @@ function buildPressReturnScript() {
 async function wait2(ms) {
   await new Promise((resolve) => setTimeout(resolve, ms));
 }
+function findMenuItem(items, partial) {
+  const needle = partial.toLowerCase();
+  return items.find((item) => item.toLowerCase().includes(needle));
+}
+async function activateQuickTime(appName2 = defaultQuickTimeAppName) {
+  await runAppleScript(buildActivateQuickTimeScript(appName2));
+}
+async function listQuickTimeFileMenuItems(appName2 = defaultQuickTimeAppName) {
+  const { stdout } = await runAppleScript(buildListQuickTimeFileMenuItemsScript(appName2));
+  return parseQuickTimeMenuItems(stdout);
+}
+async function clickQuickTimeFileMenuItem(appName2, itemName) {
+  const items = await listQuickTimeFileMenuItems(appName2);
+  if (!items.includes(itemName)) {
+    const available = items.length > 0 ? items.join(", ") : "none";
+    throw new Error(
+      `QuickTime File menu item "${itemName}" not available. Available items: ${available}`
+    );
+  }
+  await runAppleScript(buildClickQuickTimeFileMenuItemScript(appName2, itemName));
+}
+async function pressQuickTimeStartShortcut() {
+  await runAppleScript(buildQuickTimeStartShortcutScript());
+}
+async function pressQuickTimeStopShortcut() {
+  await runAppleScript(buildQuickTimeStopShortcutScript());
+}
+async function pressQuickTimeSaveShortcut() {
+  await runAppleScript(buildQuickTimeSaveShortcutScript());
+}
+async function pressReturn() {
+  await runAppleScript(buildPressReturnScript());
+}
+async function startQuickTimeRecording(appName2 = defaultQuickTimeAppName) {
+  await activateQuickTime(appName2);
+  const items = await listQuickTimeFileMenuItems(appName2);
+  const newScreenRecordingItem = findMenuItem(items, "new screen recording");
+  if (newScreenRecordingItem) {
+    await clickQuickTimeFileMenuItem(appName2, newScreenRecordingItem);
+  } else {
+    await pressQuickTimeStartShortcut();
+  }
+  await wait2(preConfirmDelay);
+  await pressReturn();
+  await wait2(postStartDelay);
+}
+async function stopQuickTimeRecording(appName2 = defaultQuickTimeAppName) {
+  await activateQuickTime(appName2);
+  const items = await listQuickTimeFileMenuItems(appName2);
+  const stopScreenRecordingItem = findMenuItem(items, "stop screen recording");
+  if (stopScreenRecordingItem) {
+    await clickQuickTimeFileMenuItem(appName2, stopScreenRecordingItem);
+  } else {
+    await pressQuickTimeStopShortcut();
+  }
+  await wait2(postStopDelay);
+}
+async function exportQuickTimeRecording(appName2 = defaultQuickTimeAppName) {
+  await activateQuickTime(appName2);
+  const items = await listQuickTimeFileMenuItems(appName2);
+  const saveItem = findMenuItem(items, "save");
+  if (saveItem) {
+    await clickQuickTimeFileMenuItem(appName2, saveItem);
+  } else {
+    await pressQuickTimeSaveShortcut();
+  }
+  await wait2(exportDialogConfirmDelay);
+  await pressReturn();
+  await wait2(exportDelay);
+}
+
+// ../../packages/adapters-screenstudio/src/menu-controls.ts
+function quote2(value) {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+function normalizeMenuItem2(raw) {
+  return raw.trim();
+}
+function parseMenuItems(stdout) {
+  if (!stdout.trim()) {
+    return [];
+  }
+  return stdout.split(",").map(normalizeMenuItem2).filter((item) => item.length > 0 && item !== "missing value");
+}
+function buildActivateScreenStudioScript(appName2) {
+  return `tell application "${quote2(appName2)}" to activate`;
+}
+function buildListRecordMenuItemsScript(appName2) {
+  return `tell application "System Events" to tell process "${quote2(appName2)}" to get name of every menu item of menu "Record" of menu bar 1`;
+}
+function buildClickRecordMenuItemScript(appName2, itemName) {
+  return `tell application "System Events" to tell process "${quote2(appName2)}" to click menu item "${quote2(itemName)}" of menu "Record" of menu bar 1`;
+}
+function buildPressReturnScript2() {
+  return 'tell application "System Events" to key code 36';
+}
+async function wait3(ms) {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
 async function activateScreenStudio(appName2) {
   await runAppleScript(buildActivateScreenStudioScript(appName2));
 }
@@ -4878,39 +5354,39 @@ async function clickRecordMenuItem(appName2, itemName) {
   }
   await runAppleScript(buildClickRecordMenuItemScript(appName2, itemName));
 }
-async function pressReturn() {
-  await runAppleScript(buildPressReturnScript());
+async function pressReturn2() {
+  await runAppleScript(buildPressReturnScript2());
 }
 
 // ../../packages/adapters-screenstudio/src/recorder.ts
 var appName = process.env.SCREENSTUDIO_APP_NAME ?? "Screen Studio";
-function int(value, fallback) {
+function int2(value, fallback) {
   const parsed = Number(value);
   return Number.isFinite(parsed) ? parsed : fallback;
 }
-var preConfirmDelay = int(process.env.SCREENSTUDIO_PRE_CONFIRM_DELAY_MS, 800);
-var postStartDelay = int(process.env.SCREENSTUDIO_POST_START_DELAY_MS, 1200);
-var postStopDelay = int(process.env.SCREENSTUDIO_POST_STOP_DELAY_MS, 800);
-var exportDialogConfirmDelay = int(process.env.SCREENSTUDIO_EXPORT_DIALOG_CONFIRM_DELAY_MS, 800);
-var exportDelay = int(process.env.SCREENSTUDIO_EXPORT_DELAY_MS, 2500);
+var preConfirmDelay2 = int2(process.env.SCREENSTUDIO_PRE_CONFIRM_DELAY_MS, 800);
+var postStartDelay2 = int2(process.env.SCREENSTUDIO_POST_START_DELAY_MS, 1200);
+var postStopDelay2 = int2(process.env.SCREENSTUDIO_POST_STOP_DELAY_MS, 800);
+var exportDialogConfirmDelay2 = int2(process.env.SCREENSTUDIO_EXPORT_DIALOG_CONFIRM_DELAY_MS, 800);
+var exportDelay2 = int2(process.env.SCREENSTUDIO_EXPORT_DELAY_MS, 2500);
 async function startRecording() {
   await activateScreenStudio(appName);
   await clickRecordMenuItem(appName, "Record display");
-  await wait2(preConfirmDelay);
-  await pressReturn();
-  await wait2(postStartDelay);
+  await wait3(preConfirmDelay2);
+  await pressReturn2();
+  await wait3(postStartDelay2);
 }
 async function stopRecording() {
   await activateScreenStudio(appName);
   await clickRecordMenuItem(appName, "Stop recording");
-  await wait2(postStopDelay);
+  await wait3(postStopDelay2);
 }
 async function exportRecording() {
   await activateScreenStudio(appName);
   await clickRecordMenuItem(appName, "Export and save to file");
-  await wait2(exportDialogConfirmDelay);
-  await pressReturn();
-  await wait2(exportDelay);
+  await wait3(exportDialogConfirmDelay2);
+  await pressReturn2();
+  await wait3(exportDelay2);
 }
 
 // ../../packages/orchestrator/src/retry-policy.ts
@@ -4932,9 +5408,31 @@ async function withRetry(fn, opts = {}) {
 }
 
 // ../../packages/orchestrator/src/engine.ts
+async function startRecorder(recorder) {
+  if (recorder === "screenstudio") {
+    await startRecording();
+    return;
+  }
+  await startQuickTimeRecording();
+}
+async function stopRecorder(recorder) {
+  if (recorder === "screenstudio") {
+    await stopRecording();
+    return;
+  }
+  await stopQuickTimeRecording();
+}
+async function exportRecorder(recorder) {
+  if (recorder === "screenstudio") {
+    await exportRecording();
+    return;
+  }
+  await exportQuickTimeRecording();
+}
 async function runEngine(input) {
   const run2 = await createRunContext();
   let state = "INIT";
+  const recorder = input.recorder ?? "screenstudio";
   const shouldExport = input.flows.some((flow) => flow.steps.some((step) => step.action === "recorder_export"));
   const files = {
     events: run2.eventsFile
@@ -4956,7 +5454,7 @@ async function runEngine(input) {
     await emit("start_app.done");
     state = "START_RECORDER";
     await emit("recorder.start.begin");
-    await startRecording();
+    await startRecorder(recorder);
     await page.bringToFront();
     await emit("recorder.start.done");
     state = "RUN_FLOW";
@@ -4983,12 +5481,12 @@ async function runEngine(input) {
     }
     state = "STOP_RECORDER";
     await emit("recorder.stop.begin");
-    await stopRecording();
+    await stopRecorder(recorder);
     await emit("recorder.stop.done");
     if (shouldExport) {
       state = "EXPORT";
       await emit("recorder.export.begin");
-      await exportRecording();
+      await exportRecorder(recorder);
       await emit("recorder.export.done");
     }
     state = "VERIFY_ARTIFACTS";
@@ -5049,12 +5547,12 @@ async function runEngine(input) {
     if (closeApp) {
       await closeApp();
     }
-    await fs6.mkdir(run2.runDir, { recursive: true });
+    await fs7.mkdir(run2.runDir, { recursive: true });
   }
 }
 
 // src/commands/config.ts
-import fs7 from "node:fs/promises";
+import fs8 from "node:fs/promises";
 import path8 from "node:path";
 
 // src/commands/path-utils.ts
@@ -5109,6 +5607,13 @@ function optionalBoolean(value, key, label) {
   }
   return value;
 }
+function optionalRecorder(value, key, label) {
+  if (value === void 0) return void 0;
+  if (value === "quicktime" || value === "screenstudio") {
+    return value;
+  }
+  throw new Error(`${label} field "${key}" must be "quicktime" or "screenstudio".`);
+}
 function parseRuntimeConfigFile(value, label) {
   const obj = ensureObject(value, label);
   return {
@@ -5116,13 +5621,14 @@ function parseRuntimeConfigFile(value, label) {
     startCommand: optionalString(obj.startCommand, "startCommand", label),
     healthPath: optionalString(obj.healthPath, "healthPath", label),
     headless: optionalBoolean(obj.headless, "headless", label),
+    recorder: optionalRecorder(obj.recorder, "recorder", label),
     bootstrapReport: optionalString(obj.bootstrapReport, "bootstrapReport", label),
     runsDir: optionalString(obj.runsDir, "runsDir", label)
   };
 }
 async function readConfigFile(filePath, label) {
   try {
-    const raw = await fs7.readFile(filePath, "utf8");
+    const raw = await fs8.readFile(filePath, "utf8");
     const parsed = JSON.parse(raw);
     return {
       exists: true,
@@ -5179,7 +5685,7 @@ async function resolveRuntimeConfig(overrides = {}) {
   const bootstrapReportPath = resolveFromWorkspace(bootstrapPathField.value);
   let bootstrap = null;
   try {
-    const raw = await fs7.readFile(bootstrapReportPath, "utf8");
+    const raw = await fs8.readFile(bootstrapReportPath, "utf8");
     const parsed = bootstrapReportSchema.parse(JSON.parse(raw));
     bootstrap = { startCommand: parsed.startCommand, healthPath: parsed.healthPath };
   } catch (error) {
@@ -5219,6 +5725,14 @@ async function resolveRuntimeConfig(overrides = {}) {
     ],
     false
   );
+  const recorder = chooseString(
+    [
+      { value: overrides.recorder, source: "flag" },
+      { value: project.config.recorder, source: "project-config" },
+      { value: user.config.recorder, source: "user-config" }
+    ],
+    "quicktime"
+  );
   const runsDir = chooseString(
     [
       { value: overrides.runsDir, source: "flag" },
@@ -5234,6 +5748,7 @@ async function resolveRuntimeConfig(overrides = {}) {
       startCommand: startCommand.value,
       healthPath: healthPath.value,
       headless: headless.value,
+      recorder: recorder.value,
       runsDir: runsDir.value
     },
     sources: {
@@ -5241,6 +5756,7 @@ async function resolveRuntimeConfig(overrides = {}) {
       startCommand: startCommand.source,
       healthPath: healthPath.source,
       headless: headless.source,
+      recorder: recorder.source,
       runsDir: runsDir.source
     },
     files: {
@@ -5266,6 +5782,7 @@ async function configShowCommand(opts = {}) {
   );
   console.log(`- healthPath: ${resolved.values.healthPath} (${resolved.sources.healthPath})`);
   console.log(`- headless: ${String(resolved.values.headless)} (${resolved.sources.headless})`);
+  console.log(`- recorder: ${resolved.values.recorder} (${resolved.sources.recorder})`);
   console.log(`- runsDir: ${resolved.values.runsDir} (${resolved.sources.runsDir})`);
   console.log(`- project config: ${resolved.files.projectConfigPath} (${resolved.files.projectConfigExists ? "found" : "missing"})`);
   console.log(`- user config: ${resolved.files.userConfigPath} (${resolved.files.userConfigExists ? "found" : "missing"})`);
@@ -5303,6 +5820,7 @@ async function configCheckCommand(opts = {}) {
   console.log(`- baseUrl: ${resolved.values.baseUrl}`);
   console.log(`- healthPath: ${resolved.values.healthPath}`);
   console.log(`- headless: ${String(resolved.values.headless)}`);
+  console.log(`- recorder: ${resolved.values.recorder}`);
   console.log(`- runsDir: ${resolved.values.runsDir}`);
   if (warnings.length > 0) {
     console.log(kleur_default.yellow("Warnings:"));
@@ -5392,7 +5910,52 @@ async function screenstudioPrepCommand(appName2 = defaultScreenStudioAppName) {
   await runScreenStudioPreflight({ appName: appName2, ensurePermissions: true, quiet: false });
 }
 
+// src/commands/quicktime-prep.ts
+var defaultQuickTimeAppName2 = process.env.QUICKTIME_APP_NAME ?? "QuickTime Player";
+function hasScreenRecordingEntry(items) {
+  return items.some((item) => item.toLowerCase().includes("new screen recording"));
+}
+async function runQuickTimePreflight(opts = {}) {
+  const appName2 = opts.appName ?? defaultQuickTimeAppName2;
+  const ensurePermissions = opts.ensurePermissions ?? true;
+  if (ensurePermissions) {
+    await ensureAutomationPermissions();
+  }
+  await activateQuickTime(appName2);
+  const items = await listQuickTimeFileMenuItems(appName2);
+  if (items.length === 0) {
+    throw new Error(
+      `QuickTime File menu is empty for app "${appName2}". Ensure QuickTime Player is running and menu automation is allowed.`
+    );
+  }
+  if (!hasScreenRecordingEntry(items)) {
+    throw new Error(
+      `QuickTime File menu does not expose "New Screen Recording" for "${appName2}". Found: ${items.join(", ")}`
+    );
+  }
+  const result = {
+    appName: appName2,
+    fileMenuItems: items
+  };
+  if (!opts.quiet) {
+    console.log(kleur_default.green("QuickTime prep passed."));
+    console.log(`- App: ${appName2}`);
+    console.log(`- File menu items: ${items.join(", ")}`);
+  }
+  return result;
+}
+async function quicktimePrepCommand(appName2 = defaultQuickTimeAppName2) {
+  await runQuickTimePreflight({ appName: appName2, ensurePermissions: true, quiet: false });
+}
+
 // src/commands/run.ts
+var explicitExportIntentMatchers = [
+  /\bexport(?:ed|ing)?\b/i,
+  /\bdownload(?:ed|ing)?\b/i,
+  /\bsave(?:\s+(?:the|to|as|a|an))*\s+(?:video|recording|file)\b/i,
+  /\bshareable\s+link\b/i,
+  /\bcopy\s+to\s+clipboard\b/i
+];
 function isWhitespace(char) {
   return /\s/.test(char);
 }
@@ -5400,7 +5963,7 @@ function parseStartCommand(raw) {
   const tokens = [];
   let current = "";
   let tokenStarted = false;
-  let quote2 = null;
+  let quote3 = null;
   let escaped = false;
   for (let index = 0; index < raw.length; index += 1) {
     const char = raw[index];
@@ -5410,14 +5973,14 @@ function parseStartCommand(raw) {
       escaped = false;
       continue;
     }
-    if (char === "\\" && quote2 !== "'") {
+    if (char === "\\" && quote3 !== "'") {
       escaped = true;
       tokenStarted = true;
       continue;
     }
-    if (quote2) {
-      if (char === quote2) {
-        quote2 = null;
+    if (quote3) {
+      if (char === quote3) {
+        quote3 = null;
       } else {
         current += char;
       }
@@ -5425,7 +5988,7 @@ function parseStartCommand(raw) {
       continue;
     }
     if (char === '"' || char === "'") {
-      quote2 = char;
+      quote3 = char;
       tokenStarted = true;
       continue;
     }
@@ -5443,7 +6006,7 @@ function parseStartCommand(raw) {
   if (escaped) {
     throw new Error("Start command ends with an escape character.");
   }
-  if (quote2) {
+  if (quote3) {
     throw new Error("Start command contains an unterminated quote.");
   }
   if (tokenStarted) {
@@ -5455,6 +6018,32 @@ function parseStartCommand(raw) {
   const [command, ...args] = tokens;
   return { command, args };
 }
+function flowRequestsExport(flows) {
+  return flows.some((flow) => flow.steps.some((step) => step.action === "recorder_export"));
+}
+function parseBooleanFromEnv(name, env = process.env) {
+  const raw = env[name];
+  if (!raw) return void 0;
+  const normalized = raw.trim().toLowerCase();
+  if (["1", "true", "yes", "on"].includes(normalized)) return true;
+  if (["0", "false", "no", "off"].includes(normalized)) return false;
+  throw new Error(`Invalid ${name} value: ${raw}. Expected true or false.`);
+}
+function intentAllowsExport(intentLabel) {
+  const normalized = intentLabel.trim();
+  if (!normalized) return false;
+  return explicitExportIntentMatchers.some((matcher) => matcher.test(normalized));
+}
+function resolveExportPermission(intentLabel, opts = {}) {
+  if (opts.allowExport !== void 0) {
+    return opts.allowExport;
+  }
+  const envOverride = parseBooleanFromEnv("STUDIOFLOW_ALLOW_EXPORT");
+  if (envOverride !== void 0) {
+    return envOverride;
+  }
+  return intentAllowsExport(intentLabel);
+}
 async function waitForHealth(healthUrl, timeoutMs = 45e3) {
   const start = Date.now();
   let lastError = null;
@@ -5505,7 +6094,23 @@ async function startAppLifecycle(baseUrl, startCommand, healthPath) {
 function formatDuration(start) {
   return `${((Date.now() - start) / 1e3).toFixed(1)}s`;
 }
-async function runWithFlows(intentLabel, flowIds, flows, runtime) {
+async function runRecorderPreflight(recorder) {
+  if (recorder === "screenstudio") {
+    const prep2 = await runScreenStudioPreflight({ ensurePermissions: false, quiet: true });
+    return {
+      label: "Screen Studio",
+      itemsLabel: "Record menu",
+      menuItems: prep2.recordMenuItems
+    };
+  }
+  const prep = await runQuickTimePreflight({ ensurePermissions: false, quiet: true });
+  return {
+    label: "QuickTime",
+    itemsLabel: "File menu",
+    menuItems: prep.fileMenuItems
+  };
+}
+async function runWithFlows(intentLabel, flowIds, flows, runtime, opts = {}) {
   const chromium2 = await ensureChromiumInstalled({ autoInstall: true });
   if (!chromium2.installed) {
     throw new Error("Playwright Chromium is not installed. Run `studioflow setup` and retry.");
@@ -5515,11 +6120,12 @@ async function runWithFlows(intentLabel, flowIds, flows, runtime) {
   }
   await ensureAutomationPermissions();
   try {
-    const prep = await runScreenStudioPreflight({ ensurePermissions: false, quiet: true });
-    console.log(`Screen Studio preflight: ready (${prep.recordMenuItems.join(", ")})`);
+    const prep = await runRecorderPreflight(runtime.values.recorder);
+    console.log(`${prep.label} preflight: ready (${prep.itemsLabel}: ${prep.menuItems.join(", ")})`);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`Screen Studio preflight failed: ${message}. Run \`studioflow screenstudio-prep\` for diagnostics.`);
+    const diagnosticsCommand = runtime.values.recorder === "screenstudio" ? "studioflow screenstudio-prep" : "studioflow quicktime-prep";
+    throw new Error(`${runtime.values.recorder} preflight failed: ${message}. Run \`${diagnosticsCommand}\` for diagnostics.`);
   }
   for (const flow of flows) {
     const validation = validateFlowDefinition(flow);
@@ -5527,6 +6133,11 @@ async function runWithFlows(intentLabel, flowIds, flows, runtime) {
       throw new Error(`Flow ${flow.id} failed validation: ${validation.errors.join("; ")}`);
     }
   }
+  if (flowRequestsExport(flows) && !resolveExportPermission(intentLabel, opts)) {
+    throw new Error(
+      "Flow includes recorder_export, but the run intent does not explicitly request export. Remove recorder_export, include export language in --intent, or pass --allow-export true."
+    );
+  }
   const started = Date.now();
   console.log(kleur_default.bold("StudioFlow Run"));
   console.log(`Intent: ${intentLabel}`);
@@ -5535,6 +6146,7 @@ async function runWithFlows(intentLabel, flowIds, flows, runtime) {
   console.log(`Start command: ${runtime.values.startCommand ?? "(not configured)"}`);
   console.log(`Health path: ${runtime.values.healthPath}`);
   console.log(`Headless: ${String(runtime.values.headless)}`);
+  console.log(`Recorder: ${runtime.values.recorder}`);
   console.log(`Runs dir: ${runtime.values.runsDir}`);
   const previousRunsDir = process.env.STUDIOFLOW_RUNS_DIR;
   process.env.STUDIOFLOW_RUNS_DIR = runtime.values.runsDir;
@@ -5544,6 +6156,7 @@ async function runWithFlows(intentLabel, flowIds, flows, runtime) {
       flows,
       baseUrl: runtime.values.baseUrl,
       headless: runtime.values.headless,
+      recorder: runtime.values.recorder,
       startApp: async () => startAppLifecycle(runtime.values.baseUrl, runtime.values.startCommand, runtime.values.healthPath)
     });
     console.log(kleur_default.green("Run completed successfully."));
@@ -5565,14 +6178,14 @@ async function runWithFlows(intentLabel, flowIds, flows, runtime) {
     }
   }
 }
-async function runFlowFileCommand(flowPath, sourceIntent = "artifact flow", overrides) {
+async function runFlowFileCommand(flowPath, sourceIntent = "artifact flow", overrides, opts = {}) {
   if (!flowPath) {
     throw new Error("Usage: studioflow run --flow <path/to/flow.json|yaml>");
   }
   const resolvedPath = resolveFromWorkspace(flowPath);
   const runtime = await resolveRuntimeConfig(overrides);
   const flow = await loadFlowFromFile(resolvedPath);
-  await runWithFlows(sourceIntent, [flow.id], [flow], runtime);
+  await runWithFlows(sourceIntent, [flow.id], [flow], runtime, opts);
 }
 
 // src/commands/list-flows.ts
@@ -5589,20 +6202,23 @@ async function doctorCommand() {
   const permissions = await checkPermissions();
   const checks = [
     {
-      name: "Screen Studio installed",
-      ok: permissions.screenStudioInstalled
+      name: "Screen Studio installed (optional)",
+      ok: permissions.screenStudioInstalled,
+      required: false
     },
     {
       name: "AppleScript available",
-      ok: permissions.canRunAppleScript
+      ok: permissions.canRunAppleScript,
+      required: true
     },
     {
       name: "Keystroke automation allowed",
-      ok: permissions.canSendKeystrokes
+      ok: permissions.canSendKeystrokes,
+      required: true
     }
   ];
   for (const check of checks) {
-    const mark = check.ok ? kleur_default.green("PASS") : kleur_default.red("FAIL");
+    const mark = check.ok ? kleur_default.green("PASS") : check.required ? kleur_default.red("FAIL") : kleur_default.yellow("WARN");
     console.log(`${mark} ${check.name}`);
   }
   if (permissions.notes.length > 0) {
@@ -5611,7 +6227,7 @@ async function doctorCommand() {
       console.log(`- ${note}`);
     }
   }
-  const failed = checks.filter((c) => !c.ok);
+  const failed = checks.filter((c) => c.required && !c.ok);
   if (failed.length > 0) {
     await triggerPermissionPrompts();
     await openPermissionSettings();
@@ -5623,10 +6239,10 @@ async function doctorCommand() {
 }
 
 // src/commands/discover.ts
-import fs8 from "node:fs/promises";
+import fs9 from "node:fs/promises";
 import path9 from "node:path";
 async function walk(dir, acc = []) {
-  const entries = await fs8.readdir(dir, { withFileTypes: true });
+  const entries = await fs9.readdir(dir, { withFileTypes: true });
   for (const entry of entries) {
     if (["node_modules", ".next", ".git", "dist", ".runs"].includes(entry.name)) continue;
     const fullPath = path9.join(dir, entry.name);
@@ -5673,7 +6289,7 @@ async function detectPackageManager(root) {
   ];
   for (const lock of lockfiles) {
     try {
-      await fs8.access(path9.join(root, lock.file));
+      await fs9.access(path9.join(root, lock.file));
       return lock.name;
     } catch {
     }
@@ -5725,7 +6341,7 @@ async function discoverCommand(outDir = "artifacts") {
   const root = workspaceRoot();
   const files = await walk(root);
   const pkgPath = path9.join(root, "package.json");
-  const pkg = JSON.parse(await fs8.readFile(pkgPath, "utf8"));
+  const pkg = JSON.parse(await fs9.readFile(pkgPath, "utf8"));
   const packageManager = await detectPackageManager(root);
   const projectType = detectProjectType(pkg, files);
   const frameworkHints = [
@@ -5760,7 +6376,7 @@ async function discoverCommand(outDir = "artifacts") {
   }));
   const inferredEdges = [];
   for (const routeFile of routeFilesWithPaths) {
-    const raw = await fs8.readFile(routeFile.filePath, "utf8");
+    const raw = await fs9.readFile(routeFile.filePath, "utf8");
     inferredEdges.push(...inferEdgesFromSource(routeFile.route, routeFile.filePath, raw, routeSet));
   }
   const deduped = Array.from(
@@ -5774,11 +6390,11 @@ async function discoverCommand(outDir = "artifacts") {
   structureReportSchema.parse(structureReport);
   navigationGraphSchema.parse(graph);
   const outputDir = resolveFromWorkspace(outDir);
-  await fs8.mkdir(outputDir, { recursive: true });
+  await fs9.mkdir(outputDir, { recursive: true });
   const structurePath = path9.join(outputDir, "structure-report.json");
   const graphPath = path9.join(outputDir, "navigation-graph.json");
-  await fs8.writeFile(structurePath, JSON.stringify(structureReport, null, 2), "utf8");
-  await fs8.writeFile(graphPath, JSON.stringify(graph, null, 2), "utf8");
+  await fs9.writeFile(structurePath, JSON.stringify(structureReport, null, 2), "utf8");
+  await fs9.writeFile(graphPath, JSON.stringify(graph, null, 2), "utf8");
   console.log(kleur_default.green("Discovery complete."));
   console.log(`- Structure report: ${structurePath}`);
   console.log(`- Navigation graph: ${graphPath}`);
@@ -5806,7 +6422,7 @@ async function validateCommand(flowPath) {
 }
 
 // src/commands/bootstrap.ts
-import fs9 from "node:fs/promises";
+import fs10 from "node:fs/promises";
 import path10 from "node:path";
 async function detectPackageManager2(root) {
   const lockfiles = [
@@ -5816,7 +6432,7 @@ async function detectPackageManager2(root) {
   ];
   for (const lock of lockfiles) {
     try {
-      await fs9.access(path10.join(root, lock.file));
+      await fs10.access(path10.join(root, lock.file));
       return lock.manager;
     } catch {
     }
@@ -5824,7 +6440,7 @@ async function detectPackageManager2(root) {
   return "unknown";
 }
 async function walk2(dir, acc = []) {
-  const entries = await fs9.readdir(dir, { withFileTypes: true });
+  const entries = await fs10.readdir(dir, { withFileTypes: true });
   for (const entry of entries) {
     if (["node_modules", ".next", ".git", "dist", ".runs"].includes(entry.name)) continue;
     const fullPath = path10.join(dir, entry.name);
@@ -5864,7 +6480,7 @@ function defaultHealthPath(projectType) {
 async function bootstrapCommand(outPath = "artifacts/bootstrap.json") {
   const root = workspaceRoot();
   const pkgPath = path10.join(root, "package.json");
-  const pkg = JSON.parse(await fs9.readFile(pkgPath, "utf8"));
+  const pkg = JSON.parse(await fs10.readFile(pkgPath, "utf8"));
   const packageManager = await detectPackageManager2(root);
   const files = await walk2(root);
   const projectType = detectProjectType2(pkg, files);
@@ -5885,8 +6501,8 @@ async function bootstrapCommand(outPath = "artifacts/bootstrap.json") {
   };
   const validated = bootstrapReportSchema.parse(report);
   const resolved = resolveFromWorkspace(outPath);
-  await fs9.mkdir(path10.dirname(resolved), { recursive: true });
-  await fs9.writeFile(resolved, JSON.stringify(validated, null, 2), "utf8");
+  await fs10.mkdir(path10.dirname(resolved), { recursive: true });
+  await fs10.writeFile(resolved, JSON.stringify(validated, null, 2), "utf8");
   console.log(kleur_default.green("Bootstrap report generated."));
   console.log(`- Output: ${resolved}`);
   console.log(`- Start command: ${validated.startCommand}`);
@@ -5894,26 +6510,142 @@ async function bootstrapCommand(outPath = "artifacts/bootstrap.json") {
 }
 
 // src/commands/setup.ts
-import fs11 from "node:fs/promises";
+import fs12 from "node:fs/promises";
 import path12 from "node:path";
 
 // src/commands/install-skills.ts
-import fs10 from "node:fs/promises";
+import { createHash } from "node:crypto";
+import fs11 from "node:fs/promises";
 import path11 from "node:path";
-import { fileURLToPath as fileURLToPath2 } from "node:url";
-var __dirname2 = path11.dirname(fileURLToPath2(import.meta.url));
+import { fileURLToPath as fileURLToPath3 } from "node:url";
+var __dirname2 = path11.dirname(fileURLToPath3(import.meta.url));
 var bundledSkillNames = ["studioflow-cli", "studioflow-investigate"];
+var skillManifestFile = "manifest.json";
+var skillMetadataFile = ".studioflow-skill.json";
+var packageName = "studioflow";
 async function pathExists(target) {
   try {
-    await fs10.access(target);
+    await fs11.access(target);
     return true;
   } catch {
     return false;
   }
 }
+function toPosixPath(value) {
+  return value.split(path11.sep).join("/");
+}
+async function listFilesRecursively(rootDir2) {
+  const entries = await fs11.readdir(rootDir2, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    const fullPath = path11.join(rootDir2, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await listFilesRecursively(fullPath));
+      continue;
+    }
+    if (entry.isFile()) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+async function hashDirectoryContents(rootDir2) {
+  const hasher = createHash("sha256");
+  const files = await listFilesRecursively(rootDir2);
+  for (const filePath of files) {
+    const relativePath = toPosixPath(path11.relative(rootDir2, filePath));
+    hasher.update(relativePath);
+    hasher.update("\n");
+    hasher.update(await fs11.readFile(filePath));
+    hasher.update("\n");
+  }
+  return hasher.digest("hex");
+}
+async function resolveCliPackageVersion(sourceDir) {
+  const candidates = [
+    path11.resolve(sourceDir, "../package.json"),
+    path11.resolve(__dirname2, "../../package.json"),
+    path11.resolve(process.cwd(), "apps/cli/package.json")
+  ];
+  for (const candidate of candidates) {
+    try {
+      const raw = await fs11.readFile(candidate, "utf8");
+      const parsed = JSON.parse(raw);
+      if (parsed.name === packageName && typeof parsed.version === "string") {
+        return parsed.version;
+      }
+    } catch {
+    }
+  }
+  return "0.0.0";
+}
+function isValidManifest(value) {
+  if (!value || typeof value !== "object") return false;
+  const manifest = value;
+  if (manifest.schemaVersion !== 1 || manifest.packageName !== packageName || typeof manifest.packageVersion !== "string" || !manifest.skills || typeof manifest.skills !== "object") {
+    return false;
+  }
+  return bundledSkillNames.every((name) => {
+    const entry = manifest.skills[name];
+    return Boolean(entry && typeof entry.hash === "string" && entry.hash.length > 0);
+  });
+}
+async function resolveBundledSkillsManifest(sourceDir) {
+  const manifestPath = path11.join(sourceDir, skillManifestFile);
+  if (await pathExists(manifestPath)) {
+    try {
+      const raw = await fs11.readFile(manifestPath, "utf8");
+      const parsed = JSON.parse(raw);
+      if (isValidManifest(parsed)) {
+        return parsed;
+      }
+    } catch {
+    }
+  }
+  const skills = {};
+  for (const skillName of bundledSkillNames) {
+    const skillPath = path11.join(sourceDir, skillName);
+    skills[skillName] = {
+      hash: await hashDirectoryContents(skillPath)
+    };
+  }
+  return {
+    schemaVersion: 1,
+    packageName,
+    packageVersion: await resolveCliPackageVersion(sourceDir),
+    skills
+  };
+}
+async function readInstalledSkillMetadata(skillDir) {
+  const metadataPath = path11.join(skillDir, skillMetadataFile);
+  if (!await pathExists(metadataPath)) {
+    return null;
+  }
+  try {
+    const raw = await fs11.readFile(metadataPath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.packageName === "string" && typeof parsed.cliVersion === "string" && typeof parsed.skillHash === "string" && typeof parsed.installedAt === "string") {
+      return parsed;
+    }
+  } catch {
+  }
+  return null;
+}
+async function writeInstalledSkillMetadata(skillDir, expectedVersion, expectedHash) {
+  const metadata = {
+    packageName,
+    cliVersion: expectedVersion,
+    skillHash: expectedHash,
+    installedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await fs11.writeFile(path11.join(skillDir, skillMetadataFile), `${JSON.stringify(metadata, null, 2)}
+`);
+}
 async function resolveBundledSkillsDir() {
   const candidates = [
     process.env.STUDIOFLOW_SKILLS_SOURCE,
+    path11.resolve(__dirname2, "../bundled/skills"),
+    path11.resolve(__dirname2, "../../bundled/skills"),
     path11.resolve(__dirname2, "../skills"),
     path11.resolve(__dirname2, "../../skills"),
     path11.resolve(__dirname2, "../../../../skills"),
@@ -5934,28 +6666,48 @@ async function resolveBundledSkillsDir() {
     `Could not locate bundled skills. Checked: ${candidates.join(", ")}. Set STUDIOFLOW_SKILLS_SOURCE if needed.`
   );
 }
-async function syncSkillsToTarget(sourceDir, targetDir, force) {
-  await fs10.mkdir(targetDir, { recursive: true });
+async function syncSkillsToTarget(sourceDir, targetDir, force, manifest) {
+  await fs11.mkdir(targetDir, { recursive: true });
   const installed = [];
+  const updated = [];
   const skipped = [];
   for (const skillName of bundledSkillNames) {
     const source = path11.join(sourceDir, skillName);
     const target = path11.join(targetDir, skillName);
     const exists = await pathExists(target);
-    if (exists && !force) {
-      skipped.push(skillName);
+    const expectedHash = manifest.skills[skillName]?.hash;
+    if (!expectedHash) {
+      throw new Error(`Missing skill hash in manifest for ${skillName}.`);
+    }
+    if (!exists) {
+      await fs11.cp(source, target, { recursive: true });
+      await writeInstalledSkillMetadata(target, manifest.packageVersion, expectedHash);
+      installed.push(skillName);
       continue;
     }
-    if (exists && force) {
-      await fs10.rm(target, { recursive: true, force: true });
+    if (force) {
+      await fs11.rm(target, { recursive: true, force: true });
+      await fs11.cp(source, target, { recursive: true });
+      await writeInstalledSkillMetadata(target, manifest.packageVersion, expectedHash);
+      installed.push(skillName);
+      continue;
     }
-    await fs10.cp(source, target, { recursive: true });
-    installed.push(skillName);
+    const currentMetadata = await readInstalledSkillMetadata(target);
+    const matchesInstalledVersion = currentMetadata?.packageName === manifest.packageName && currentMetadata.cliVersion === manifest.packageVersion && currentMetadata.skillHash === expectedHash;
+    if (matchesInstalledVersion) {
+      skipped.push(skillName);
+      continue;
+    }
+    await fs11.rm(target, { recursive: true, force: true });
+    await fs11.cp(source, target, { recursive: true });
+    await writeInstalledSkillMetadata(target, manifest.packageVersion, expectedHash);
+    updated.push(skillName);
   }
-  return { installed, skipped };
+  return { installed, updated, skipped };
 }
 async function installBundledSkills(opts = {}) {
   const sourceDir = await resolveBundledSkillsDir();
+  const manifest = await resolveBundledSkillsManifest(sourceDir);
   const force = opts.force ?? false;
   const targets = [];
   if (opts.targetDir && (opts.agent || opts.codexTargetDir || opts.claudeTargetDir)) {
@@ -5980,11 +6732,12 @@ async function installBundledSkills(opts = {}) {
   }
   const results = [];
   for (const target of targets) {
-    const synced = await syncSkillsToTarget(sourceDir, target.targetDir, force);
+    const synced = await syncSkillsToTarget(sourceDir, target.targetDir, force, manifest);
     results.push({
       targetId: target.targetId,
       targetDir: target.targetDir,
       installed: synced.installed,
+      updated: synced.updated,
       skipped: synced.skipped
     });
   }
@@ -6001,8 +6754,11 @@ async function installSkillsCommand(opts = {}) {
     if (target.installed.length > 0) {
       console.log(`- Installed (${label}): ${target.installed.join(", ")}`);
     }
+    if (target.updated.length > 0) {
+      console.log(`- Updated (${label}): ${target.updated.join(", ")}`);
+    }
     if (target.skipped.length > 0) {
-      console.log(kleur_default.yellow(`- Skipped (${label}, already present): ${target.skipped.join(", ")}`));
+      console.log(kleur_default.yellow(`- Skipped (${label}, up to date): ${target.skipped.join(", ")}`));
     }
   }
   if (result.targets.some((target) => target.skipped.length > 0)) {
@@ -6017,8 +6773,8 @@ function setupStatePath() {
 }
 async function writeSetupState(payload) {
   const statePath = setupStatePath();
-  await fs11.mkdir(path12.dirname(statePath), { recursive: true });
-  await fs11.writeFile(statePath, JSON.stringify(payload, null, 2), "utf8");
+  await fs12.mkdir(path12.dirname(statePath), { recursive: true });
+  await fs12.writeFile(statePath, JSON.stringify(payload, null, 2), "utf8");
 }
 async function setupCommand(opts = {}) {
   console.log(kleur_default.bold("StudioFlow setup"));
@@ -6049,14 +6805,17 @@ async function setupCommand(opts = {}) {
       if (target.installed.length > 0) {
         console.log(`- Installed (${label}): ${target.installed.join(", ")}`);
       }
+      if (target.updated.length > 0) {
+        console.log(`- Updated (${label}): ${target.updated.join(", ")}`);
+      }
       if (target.skipped.length > 0) {
-        console.log(kleur_default.yellow(`- Skipped (${label}, already present): ${target.skipped.join(", ")}`));
+        console.log(kleur_default.yellow(`- Skipped (${label}, up to date): ${target.skipped.join(", ")}`));
       }
     }
   }
   const permissions = await checkPermissions();
   const permissionChecks = [
-    { label: "Screen Studio installed", ok: permissions.screenStudioInstalled },
+    { label: "Screen Studio installed (optional)", ok: permissions.screenStudioInstalled },
     { label: "AppleScript available", ok: permissions.canRunAppleScript },
     { label: "Keystroke automation allowed", ok: permissions.canSendKeystrokes }
   ];
@@ -6081,6 +6840,7 @@ async function setupCommand(opts = {}) {
         targetId: target.targetId,
         targetDir: target.targetDir,
         installed: target.installed,
+        updated: target.updated,
         skipped: target.skipped
       }))
     } : { skipped: true }
@@ -6093,9 +6853,9 @@ async function setupCommand(opts = {}) {
 var cachedVersion = null;
 async function cliVersion() {
   if (cachedVersion) return cachedVersion;
-  const dirname = path13.dirname(fileURLToPath3(import.meta.url));
+  const dirname = path13.dirname(fileURLToPath4(import.meta.url));
   const packageJsonPath = path13.resolve(dirname, "../package.json");
-  const raw = await fs12.readFile(packageJsonPath, "utf8");
+  const raw = await fs13.readFile(packageJsonPath, "utf8");
   const parsed = JSON.parse(raw);
   cachedVersion = parsed.version ?? "0.0.0";
   return cachedVersion;
@@ -6122,6 +6882,13 @@ function readFlagValue(args, flag) {
   }
   return value;
 }
+function parseRecorder(raw, flag) {
+  if (raw === void 0) return void 0;
+  if (raw === "quicktime" || raw === "screenstudio") {
+    return raw;
+  }
+  throw new Error(`Invalid ${flag} value: ${raw}. Expected quicktime or screenstudio.`);
+}
 function parseRuntimeConfigOverrides(args) {
   const headlessRaw = readFlagValue(args, "--headless");
   return {
@@ -6130,9 +6897,16 @@ function parseRuntimeConfigOverrides(args) {
     healthPath: readFlagValue(args, "--health-path"),
     bootstrapReportPath: readFlagValue(args, "--bootstrap-report"),
     runsDir: readFlagValue(args, "--runs-dir"),
+    recorder: parseRecorder(readFlagValue(args, "--recorder"), "--recorder"),
     headless: headlessRaw ? parseBoolean(headlessRaw, "--headless") : void 0
   };
 }
+function parseRunCommandOptions(args) {
+  const allowExportRaw = readFlagValue(args, "--allow-export");
+  return {
+    allowExport: allowExportRaw ? parseBoolean(allowExportRaw, "--allow-export") : void 0
+  };
+}
 function parseSkillsAgent(raw, flag) {
   if (raw === void 0) return void 0;
   if (raw === "codex" || raw === "claude" || raw === "all") {
@@ -6152,12 +6926,13 @@ async function main() {
       const flowPath = readFlag(normalizedArgs, "--flow");
       if (!flowPath) {
         throw new Error(
-          'Usage: studioflow run --flow <path/to/flow.json|yaml> [--intent "<label>"] [--base-url <url>] [--start-command "<command>"] [--health-path <path>] [--headless <true|false>] [--bootstrap-report <path>] [--runs-dir <path>]'
+          'Usage: studioflow run --flow <path/to/flow.json|yaml> [--intent "<label>"] [--allow-export <true|false>] [--base-url <url>] [--start-command "<command>"] [--health-path <path>] [--headless <true|false>] [--recorder <quicktime|screenstudio>] [--bootstrap-report <path>] [--runs-dir <path>]'
         );
       }
       const sourceIntent = readFlag(normalizedArgs, "--intent") ?? "artifact flow";
       const runtimeOverrides = parseRuntimeConfigOverrides(normalizedArgs);
-      await runFlowFileCommand(flowPath, sourceIntent, runtimeOverrides);
+      const runOptions = parseRunCommandOptions(normalizedArgs);
+      await runFlowFileCommand(flowPath, sourceIntent, runtimeOverrides, runOptions);
       return;
     }
     if (command === "config") {
@@ -6174,7 +6949,7 @@ async function main() {
         return;
       }
       throw new Error(
-        "Usage: studioflow config <show|check> [--json] [--base-url <url>] [--start-command <command>] [--health-path <path>] [--headless <true|false>] [--bootstrap-report <path>] [--runs-dir <path>]"
+        "Usage: studioflow config <show|check> [--json] [--base-url <url>] [--start-command <command>] [--health-path <path>] [--headless <true|false>] [--recorder <quicktime|screenstudio>] [--bootstrap-report <path>] [--runs-dir <path>]"
       );
     }
     if (command === "discover") {
@@ -6192,6 +6967,11 @@ async function main() {
       await screenstudioPrepCommand(appName2);
       return;
     }
+    if (command === "quicktime-prep") {
+      const appName2 = readFlag(normalizedArgs, "--app-name");
+      await quicktimePrepCommand(appName2);
+      return;
+    }
     if (command === "setup") {
       await setupCommand({
         skipSkills: hasFlag(normalizedArgs, "--skip-skills"),