studioflow 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StudioFlow contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# StudioFlow CLI
+
+StudioFlow turns natural-language demo intent into deterministic UI run artifacts and executes them through Screen Studio.
+
+## Requirements
+
+- macOS (Screen Studio automation)
+- Screen Studio installed
+- Node.js 22+
+
+## Install
+
+```bash
+npm install -g studioflow
+```
+
+## Setup Runtime + Skills
+
+`setup` installs Playwright Chromium, installs bundled skills for Codex and Claude, and checks permissions.
+
+```bash
+studioflow setup
+```
+
+Bundled skills include:
+- `studioflow-investigate` (intent -> deterministic artifacts, including `artifacts/flow.json`)
+- `studioflow-cli` (artifact execution workflow)
+
+## Quick Start
+
+1. Start your agent from the project root.
+
+Codex:
+
+```bash
+cd /path/to/your/project
+codex
+```
+
+Claude Code:
+
+```bash
+cd /path/to/your/project
+claude
+```
+
+If your launcher command differs, start your usual Codex or Claude session in this repo root.
+
+2. Trigger `studioflow-investigate` to generate `artifacts/flow.json`.
+
+Paste this prompt:
+
+```text
+Use StudioFlow skill studioflow-investigate.
+Intent: "Record a demo for onboarding and billing."
+Generate artifacts/flow.json for this repo.
+If intent details are missing, ask concise follow-up questions before authoring the flow.
+```
+
+`studioflow-investigate` automatically collects project context artifacts before creating the flow.
+
+3. Validate and run:
+
+```bash
+studioflow validate --flow artifacts/flow.json
+studioflow demo --flow artifacts/flow.json --intent "onboarding and billing demo"
+```
+
+`run`/`demo` automatically performs Screen Studio preflight checks. Use manual prep only for troubleshooting.
+Headed runs auto-open a maximized browser window for cleaner recording composition.
+Runs do not auto-export by default; include `recorder_export` in flow steps only when export is explicitly needed.
+
+## Optional: Trigger Runtime Skill In Agent
+
+If you want the agent to drive execution too, use:
+
+```text
+Use StudioFlow skill studioflow-cli.
+Validate artifacts/flow.json, run the demo, and report run artifact paths.
+```
+
+## Documentation
+
+- Day 0 runbook: https://github.com/ydarar/studioflow/blob/main/docs/day0-runbook.md
+- CLI reference: https://github.com/ydarar/studioflow/blob/main/docs/cli-reference.md
+- Configuration: https://github.com/ydarar/studioflow/blob/main/docs/configuration.md
+- Smoke checklist: https://github.com/ydarar/studioflow/blob/main/docs/testing-manual-smoke.md
+- Open intent tests: https://github.com/ydarar/studioflow/blob/main/docs/studioflow-open-intent-tests.md
+- Full docs map: https://github.com/ydarar/studioflow/blob/main/docs/README.md

package/dist/index.js

@@ -7513,29 +7513,37 @@ async function assertVisible(page, selector, timeoutMs = 5e3) {
 function wait(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
-function boolEnv(name, fallback) {
-  const raw = process.env[name];
+function boolEnv(name, fallback, env = process.env) {
+  const raw = env[name];
   if (!raw) return fallback;
   const normalized = raw.trim().toLowerCase();
   if (["1", "true", "yes", "on"].includes(normalized)) return true;
   if (["0", "false", "no", "off"].includes(normalized)) return false;
   return fallback;
 }
-function intEnv(name, fallback) {
-  const raw = process.env[name];
+function intEnv(name, fallback, env = process.env) {
+  const raw = env[name];
   if (!raw) return fallback;
   const parsed = Number(raw);
   return Number.isFinite(parsed) ? parsed : fallback;
 }
-var renderCursorOverlay = boolEnv("STUDIOFLOW_RENDER_CURSOR", true);
-var defaultCursorMoveMs = intEnv("STUDIOFLOW_CURSOR_MOVE_MS", 320);
-var defaultCursorHighlightMs = intEnv("STUDIOFLOW_CURSOR_HIGHLIGHT_MS", 120);
-var realisticTyping = boolEnv("STUDIOFLOW_REALISTIC_TYPING", true);
-var typingDelayMs = Math.max(0, intEnv("STUDIOFLOW_TYPING_DELAY_MS", 35));
-var pacingAdjustmentEnabled = boolEnv("STUDIOFLOW_PACING_ADJUSTMENT", true);
-var pacingJitterEnabled = boolEnv("STUDIOFLOW_PACING_JITTER", true);
 var maxDelayMs = 6e4;
-var cursorOverlaySetupScript = `
+function resolveRuntimePacingDefaults(env = process.env) {
+  return {
+    renderCursorOverlay: boolEnv("STUDIOFLOW_RENDER_CURSOR", true, 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),
+    typingDelayMs: Math.max(0, intEnv("STUDIOFLOW_TYPING_DELAY_MS", 55, env)),
+    clickPulseMs: Math.max(0, intEnv("STUDIOFLOW_CLICK_PULSE_MS", 220, env)),
+    stepPreDelayMs: Math.max(0, intEnv("STUDIOFLOW_STEP_PRE_DELAY_MS", 90, env)),
+    stepPostDelayMs: Math.max(0, intEnv("STUDIOFLOW_STEP_POST_DELAY_MS", 130, env)),
+    stepDwellMs: Math.max(0, intEnv("STUDIOFLOW_STEP_DWELL_MS", 180, env)),
+    pacingAdjustmentEnabled: boolEnv("STUDIOFLOW_PACING_ADJUSTMENT", true, env),
+    pacingJitterEnabled: boolEnv("STUDIOFLOW_PACING_JITTER", true, env)
+  };
+}
+var cursorOverlaySetupScript = (clickPulseMs) => `
 (() => {
   const win = window;
   if (win.__studioflowCursor) return;
@@ -7548,29 +7556,32 @@ var cursorOverlaySetupScript = `
         position: fixed;
         top: 0;
         left: 0;
-        width: 16px;
-        height: 16px;
-        border-radius: 999px;
-        border: 2px solid rgba(2, 6, 23, 0.9);
-        background: rgba(255, 255, 255, 0.78);
-        box-shadow: 0 0 0 1px rgba(255, 255, 255, 0.95), 0 4px 14px rgba(2, 6, 23, 0.28);
+        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");
+        background-repeat: no-repeat;
+        background-size: 22px 30px;
         pointer-events: none;
         z-index: 2147483647;
-        transform: translate3d(8px, 8px, 0);
+        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);
       }
       #studioflow-cursor::after {
         content: "";
         position: absolute;
-        inset: -8px;
+        left: -8px;
+        top: -8px;
+        width: 20px;
+        height: 20px;
         border-radius: 999px;
         border: 2px solid rgba(59, 130, 246, 0.72);
         opacity: 0;
         transform: scale(0.65);
       }
       #studioflow-cursor.studioflow-cursor-pulse::after {
-        animation: studioflow-cursor-pulse 300ms ease-out;
+        animation: studioflow-cursor-pulse ${Math.max(0, clickPulseMs)}ms ease-out;
       }
       @keyframes studioflow-cursor-pulse {
         0% { opacity: 0.9; transform: scale(0.55); }
@@ -7591,7 +7602,7 @@ var cursorOverlaySetupScript = `
     x = nextX;
     y = nextY;
     cursor.style.transitionDuration = \`\${Math.max(0, durationMs)}ms\`;
-    cursor.style.transform = \`translate3d(\${x - 8}px, \${y - 8}px, 0)\`;
+    cursor.style.transform = \`translate3d(\${x}px, \${y}px, 0)\`;
   };
 
   win.__studioflowCursor = {
@@ -7631,40 +7642,40 @@ function jitterFactor(seed) {
   const normalized = hash / 4294967295;
   return normalized * 0.24 - 0.12;
 }
-function resolvePacedDelay(rawMs, context, channel, allowJitter = true) {
+function resolvePacedDelay(rawMs, context, runtime, channel, allowJitter = true) {
   if (!rawMs || rawMs <= 0) return 0;
   let value = rawMs;
-  const multiplier = pacingAdjustmentEnabled ? context.pacingMultiplier ?? 1 : 1;
+  const multiplier = runtime.pacingAdjustmentEnabled ? context.pacingMultiplier ?? 1 : 1;
   value *= multiplier;
-  const shouldApplyJitter = allowJitter && pacingJitterEnabled && !context.strictPacing && Boolean(context.jitterSeed);
+  const shouldApplyJitter = allowJitter && runtime.pacingJitterEnabled && !context.strictPacing && Boolean(context.jitterSeed);
   if (shouldApplyJitter) {
     value *= 1 + jitterFactor(`${context.jitterSeed}:${channel}`);
   }
   return Math.max(0, Math.min(maxDelayMs, Math.round(value)));
 }
-async function ensureCursorOverlay(page) {
-  if (!renderCursorOverlay) return;
-  await page.evaluate(cursorOverlaySetupScript);
+async function ensureCursorOverlay(page, runtime) {
+  if (!runtime.renderCursorOverlay) return;
+  await page.evaluate(cursorOverlaySetupScript(runtime.clickPulseMs));
 }
 async function getTargetCenter(page, target) {
   const box = await page.locator(target).first().boundingBox();
   if (!box) return null;
   return { x: box.x + box.width / 2, y: box.y + box.height / 2 };
 }
-async function moveCursor(page, point, durationMs) {
+async function moveCursor(page, point, durationMs, runtime) {
   await page.mouse.move(point.x, point.y, { steps: Math.max(8, Math.floor(durationMs / 16)) });
-  if (renderCursorOverlay) {
-    await ensureCursorOverlay(page);
+  if (runtime.renderCursorOverlay) {
+    await ensureCursorOverlay(page, runtime);
     await page.evaluate(cursorMoveScript(point, durationMs));
   }
 }
-async function clickPulse(page) {
-  if (!renderCursorOverlay) return;
-  await ensureCursorOverlay(page);
+async function clickPulse(page, runtime) {
+  if (!runtime.renderCursorOverlay) return;
+  await ensureCursorOverlay(page, runtime);
   await page.evaluate(cursorClickPulseScript);
 }
-async function applyPreStepPacing(page, step, context) {
-  const preDelay = resolvePacedDelay(step.preDelayMs, context, "pre");
+async function applyPreStepPacing(page, step, context, runtime) {
+  const preDelay = resolvePacedDelay(step.preDelayMs ?? runtime.stepPreDelayMs, context, runtime, "pre");
   if (preDelay > 0) {
     await wait(preDelay);
   }
@@ -7672,66 +7683,67 @@ async function applyPreStepPacing(page, step, context) {
   if (!shouldMoveCursor || !step.target) return;
   const center = await getTargetCenter(page, step.target);
   if (!center) return;
-  const moveMs = resolvePacedDelay(step.mouseMoveMs ?? defaultCursorMoveMs, context, "move");
+  const moveMs = resolvePacedDelay(step.mouseMoveMs ?? runtime.cursorMoveMs, context, runtime, "move");
   if (moveMs > 0) {
-    await moveCursor(page, center, moveMs);
+    await moveCursor(page, center, moveMs, runtime);
   }
-  const highlightMs = resolvePacedDelay(step.highlightMs ?? defaultCursorHighlightMs, context, "highlight");
+  const highlightMs = resolvePacedDelay(step.highlightMs ?? runtime.cursorHighlightMs, context, runtime, "highlight");
   if (highlightMs > 0) {
     await wait(highlightMs);
   }
 }
-async function applyPostStepPacing(step, context) {
-  const postDelay = resolvePacedDelay(step.postDelayMs, context, "post");
+async function applyPostStepPacing(step, context, runtime) {
+  const postDelay = resolvePacedDelay(step.postDelayMs ?? runtime.stepPostDelayMs, context, runtime, "post");
   if (postDelay > 0) {
     await wait(postDelay);
   }
-  const dwellDelay = resolvePacedDelay(step.dwellMs, context, "dwell");
+  const dwellDelay = resolvePacedDelay(step.dwellMs ?? runtime.stepDwellMs, context, runtime, "dwell");
   if (dwellDelay > 0) {
     await wait(dwellDelay);
   }
 }
 async function executeStep(page, step, runDir, baseUrl, context = {}) {
   const timeout = step.timeoutMs ?? 6e3;
-  await applyPreStepPacing(page, step, context);
+  const runtime = resolveRuntimePacingDefaults();
+  await applyPreStepPacing(page, step, context, runtime);
   if (step.action === "goto") {
     const target = step.value ?? "/";
     const isAbsolute = /^https?:\/\//.test(target);
     await page.goto(isAbsolute ? target : new URL(target, baseUrl).toString(), { timeout });
-    await applyPostStepPacing(step, context);
+    await applyPostStepPacing(step, context, runtime);
     return;
   }
   if (step.action === "click") {
     if (!step.target) throw new Error(`Step ${step.id} missing target`);
     await page.locator(step.target).first().click({ timeout });
-    await clickPulse(page);
-    await applyPostStepPacing(step, context);
+    await clickPulse(page, runtime);
+    await applyPostStepPacing(step, context, runtime);
     return;
   }
   if (step.action === "type") {
     if (!step.target) throw new Error(`Step ${step.id} missing target`);
     const locator = page.locator(step.target).first();
-    if (realisticTyping) {
+    if (runtime.realisticTyping) {
       await locator.click({ timeout });
-      await clickPulse(page);
+      await clickPulse(page, runtime);
       await locator.fill("", { timeout });
-      const effectiveTypingDelay = resolvePacedDelay(typingDelayMs, context, "typing", false);
+      const effectiveTypingDelay = resolvePacedDelay(runtime.typingDelayMs, context, runtime, "typing", false);
       await page.keyboard.type(step.value ?? "", { delay: effectiveTypingDelay });
     } else {
       await locator.fill(step.value ?? "", { timeout });
     }
-    await applyPostStepPacing(step, context);
+    await applyPostStepPacing(step, context, runtime);
     return;
   }
   if (step.action === "wait_for") {
     if (step.target) {
       await page.locator(step.target).first().waitFor({ state: "visible", timeout });
-      await applyPostStepPacing(step, context);
+      await applyPostStepPacing(step, context, runtime);
       return;
     }
     if (step.value) {
       await page.getByText(step.value).first().waitFor({ timeout });
-      await applyPostStepPacing(step, context);
+      await applyPostStepPacing(step, context, runtime);
       return;
     }
     throw new Error(`Step ${step.id} requires target or value for wait_for`);
@@ -7739,23 +7751,23 @@ async function executeStep(page, step, runDir, baseUrl, context = {}) {
   if (step.action === "assert_text") {
     if (!step.value) throw new Error(`Step ${step.id} missing value`);
     await assertText(page, step.value, timeout);
-    await applyPostStepPacing(step, context);
+    await applyPostStepPacing(step, context, runtime);
     return;
   }
   if (step.action === "assert_visible") {
     if (!step.target) throw new Error(`Step ${step.id} missing target`);
     await assertVisible(page, step.target, timeout);
-    await applyPostStepPacing(step, context);
+    await applyPostStepPacing(step, context, runtime);
     return;
   }
   if (step.action === "screenshot") {
     const name = step.value ?? `${step.id}.png`;
     await page.screenshot({ path: `${runDir}/screenshots/${name}.png`, fullPage: true });
-    await applyPostStepPacing(step, context);
+    await applyPostStepPacing(step, context, runtime);
     return;
   }
   if (["recorder_start", "recorder_stop", "recorder_export"].includes(step.action)) {
-    await applyPostStepPacing(step, context);
+    await applyPostStepPacing(step, context, runtime);
     return;
   }
   throw new Error(`Unsupported action: ${step.action}`);
@@ -11982,9 +11994,12 @@ import fs6 from "node:fs/promises";
 import path4 from "node:path";
 
 // ../../packages/artifacts/src/paths.ts
+import os2 from "node:os";
 import path2 from "node:path";
 function getRunsRoot() {
-  const configured = process.env.STUDIOFLOW_RUNS_DIR || ".runs";
+  const dataDir = process.env.STUDIOFLOW_DATA_DIR ?? process.env.STUDIOFLOW_HOME;
+  const defaultRunsDir = dataDir && dataDir.trim() ? path2.join(path2.resolve(dataDir), "runs") : path2.join(os2.homedir(), ".studioflow", "runs");
+  const configured = process.env.STUDIOFLOW_RUNS_DIR || defaultRunsDir;
   if (path2.isAbsolute(configured)) {
     return configured;
   }
@@ -12224,6 +12239,7 @@ async function withRetry(fn, opts = {}) {
 async function runEngine(input) {
   const run2 = await createRunContext();
   let state = "INIT";
+  const shouldExport = input.flows.some((flow) => flow.steps.some((step) => step.action === "recorder_export"));
   const files = {
     events: run2.eventsFile
   };
@@ -12273,10 +12289,12 @@ async function runEngine(input) {
     await emit("recorder.stop.begin");
     await stopRecording();
     await emit("recorder.stop.done");
-    state = "EXPORT";
-    await emit("recorder.export.begin");
-    await exportRecording();
-    await emit("recorder.export.done");
+    if (shouldExport) {
+      state = "EXPORT";
+      await emit("recorder.export.begin");
+      await exportRecording();
+      await emit("recorder.export.done");
+    }
     state = "VERIFY_ARTIFACTS";
     const planPath = path4.join(run2.runDir, "plan.json");
     await writeJsonFile(planPath, {
@@ -12354,18 +12372,18 @@ function resolveFromWorkspace(inputPath) {
 }
 
 // src/commands/runtime-paths.ts
-import os2 from "node:os";
+import os3 from "node:os";
 import path6 from "node:path";
 function getStudioflowDataDir() {
   const configured = process.env.STUDIOFLOW_DATA_DIR ?? process.env.STUDIOFLOW_HOME;
   if (configured && configured.trim()) {
     return path6.resolve(configured);
   }
-  return path6.join(os2.homedir(), ".studioflow");
+  return path6.join(os3.homedir(), ".studioflow");
 }
 function resolveAgentHome(envVar, defaultDir) {
   const configured = process.env[envVar];
-  return configured && configured.trim() ? path6.resolve(configured) : path6.join(os2.homedir(), defaultDir);
+  return configured && configured.trim() ? path6.resolve(configured) : path6.join(os3.homedir(), defaultDir);
 }
 function getCodexSkillsDir() {
   return path6.join(resolveAgentHome("CODEX_HOME", ".codex"), "skills");
@@ -12511,7 +12529,7 @@ async function resolveRuntimeConfig(overrides = {}) {
       { value: project.config.runsDir, source: "project-config" },
       { value: user.config.runsDir, source: "user-config" }
     ],
-    ".runs"
+    path7.join(getStudioflowDataDir(), "runs")
   );
   validateBaseUrl(baseUrl.value);
   return {