studioflow 0.1.4 → 0.2.0

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

@@ -8,9 +8,9 @@ This package includes:
 
 ## Requirements
 
-- macOS (Screen Studio automation)
-- Screen Studio installed
+- macOS (QuickTime/Screen Studio automation)
 - Node.js 22+
+- QuickTime Player (built into macOS) or Screen Studio
 
 ## Install
 
@@ -63,9 +63,10 @@ Record a demo for onboarding and billing.
 - validate the flow
 - execute recording through the CLI runtime
 
-`run`/`demo` automatically performs Screen Studio preflight checks. Use manual prep only for troubleshooting.
+`run`/`demo` automatically performs recorder preflight checks. QuickTime is the default backend; use `--recorder screenstudio` to opt into Screen Studio.
 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.
+Runs now also block `recorder_export` unless intent text explicitly asks for export, or `--allow-export true` is provided.
 
 ## Advanced Manual Mode (Optional)
 

package/bundled/skills/manifest.json

@@ -0,0 +1,14 @@
+{
+  "schemaVersion": 1,
+  "packageName": "studioflow",
+  "packageVersion": "0.2.0",
+  "generatedAt": "2026-02-14T18:48:19.096Z",
+  "skills": {
+    "studioflow-cli": {
+      "hash": "4328ceed07012ece8406541b2e764d2ea686af473a6ce0206458a346f2e6eed8"
+    },
+    "studioflow-investigate": {
+      "hash": "e2bf84ed56b7077575c2a875acc5b2c26cac7b34e84d8ceb213ff5d4357665fc"
+    }
+  }
+}

package/{skills → bundled/skills}/studioflow-cli/SKILL.md

@@ -13,6 +13,7 @@ Run validated artifacts through deterministic execution.
 - `artifacts/studioflow-cli-handoff.json`
 
 If handoff exists, use it as the source of truth for `flowPath`, `intentSummary`, `baseUrl`, `startCommand`, and `healthPath`.
+If handoff includes `recorder`, treat it as source of truth and preserve explicit user recorder choice.
 If present, also consume `runtimePacing` from handoff for runtime timing env values.
 
 1. Confirm artifact presence:
@@ -29,7 +30,14 @@ pnpm run setup
 pnpm run doctor
 ```
 
-If run preflight fails, collect explicit Screen Studio diagnostics:
+If run preflight fails, collect recorder-specific diagnostics:
+- For `recorder=quicktime`:
+
+```bash
+pnpm quicktime-prep
+```
+
+- For `recorder=screenstudio`:
 
 ```bash
 pnpm screenstudio-prep
@@ -44,10 +52,11 @@ pnpm validate -- --flow artifacts/flow.json
 4. Execute recording run from artifact:
 
 ```bash
-STUDIOFLOW_CURSOR_MOVE_MS=<cursorMoveMs> STUDIOFLOW_CURSOR_HIGHLIGHT_MS=<cursorHighlightMs> STUDIOFLOW_TYPING_DELAY_MS=<typingDelayMs> STUDIOFLOW_CLICK_PULSE_MS=<clickPulseMs> STUDIOFLOW_STEP_PRE_DELAY_MS=<stepPreDelayMs> STUDIOFLOW_STEP_POST_DELAY_MS=<stepPostDelayMs> STUDIOFLOW_STEP_DWELL_MS=<stepDwellMs> pnpm demo -- --flow <flowPath> --intent "<intent-summary>" --base-url <baseUrl> --start-command "<startCommand>" --health-path <healthPath>
+STUDIOFLOW_CURSOR_MOVE_MS=<cursorMoveMs> STUDIOFLOW_CURSOR_HIGHLIGHT_MS=<cursorHighlightMs> STUDIOFLOW_TYPING_DELAY_MS=<typingDelayMs> STUDIOFLOW_CLICK_PULSE_MS=<clickPulseMs> STUDIOFLOW_STEP_PRE_DELAY_MS=<stepPreDelayMs> STUDIOFLOW_STEP_POST_DELAY_MS=<stepPostDelayMs> STUDIOFLOW_STEP_DWELL_MS=<stepDwellMs> pnpm demo -- --flow <flowPath> --intent "<intent-summary>" --recorder <recorder> --base-url <baseUrl> --start-command "<startCommand>" --health-path <healthPath>
 ```
 
 Only set timing env vars that are provided (or implied by selected run-feel profile) in handoff.
+If `recorder` is missing from handoff, default to `quicktime`.
 
 5. Inspect outputs:
 - `<runsDir>/<run-id>/run.json`

package/{skills → bundled/skills}/studioflow-cli/references/handoff-spec.md

@@ -11,11 +11,12 @@
   "version": 1,
   "intentSummary": "Record only onboarding + CRM in Demo Lab",
   "flowPath": "artifacts/flow.json",
+  "recorder": "screenstudio",
   "baseUrl": "http://localhost:4280",
   "startCommand": "pnpm dev:demo-lab",
   "healthPath": "/",
   "runtimePacing": {
-    "profile": "balanced",
+    "profile": "standard",
     "cursorMoveMs": 430,
     "cursorHighlightMs": 170,
     "typingDelayMs": 55,
@@ -33,18 +34,22 @@
 - `version`
 - `intentSummary`
 - `flowPath`
+- `recorder`
 - `baseUrl`
 - `healthPath`
 
 `startCommand` is recommended. If omitted, runtime can still proceed when app is already healthy.
-`runtimePacing` is optional for conversation-driven speed tuning.
+`recorder` values: `quicktime`, `screenstudio`. If missing, default to `quicktime`.
+When intent explicitly names recorder software, preserve that recorder in handoff and execution.
+`runtimePacing` should be present for investigate-generated handoff and should drive timing env vars directly.
+Use `runtimePacing.profile` values `fast`, `standard`, `cinematic`.
 
 ## Execution mapping
 
 From payload, execute:
 
 1. `pnpm validate -- --flow <flowPath>`
-2. `pnpm demo -- --flow <flowPath> --intent "<intentSummary>" --base-url <baseUrl> --start-command "<startCommand>" --health-path <healthPath>`
+2. `pnpm demo -- --flow <flowPath> --intent "<intentSummary>" --recorder <recorder> --base-url <baseUrl> --start-command "<startCommand>" --health-path <healthPath>`
 3. If `runtimePacing` exists, set mapped env vars on the `pnpm demo` command:
    - `STUDIOFLOW_CURSOR_MOVE_MS`
    - `STUDIOFLOW_CURSOR_HIGHLIGHT_MS`
@@ -54,4 +59,8 @@ From payload, execute:
    - `STUDIOFLOW_STEP_POST_DELAY_MS`
    - `STUDIOFLOW_STEP_DWELL_MS`
 
+Preflight diagnostics mapping:
+- `recorder=quicktime` -> `pnpm quicktime-prep`
+- `recorder=screenstudio` -> `pnpm screenstudio-prep`
+
 If payload is missing, fall back to explicit user arguments or repo defaults.

package/{skills → bundled/skills}/studioflow-investigate/SKILL.md

@@ -39,11 +39,19 @@ Open-intent detection:
   - `user_goal`: what user action/outcome to demonstrate
   - `done_assertion`: what text/element proves completion
 
+Recorder selection:
+- Detect explicit recorder preference from user wording before authoring handoff:
+  - If intent says `screen studio` (or equivalent), set recorder to `screenstudio`.
+  - If intent says `quicktime` or `quicktime player`, set recorder to `quicktime`.
+  - If not specified, default to `quicktime`.
+- Treat explicit user recorder wording as authoritative over defaults.
+
 Clarification loop:
 - Max 2 rounds.
 - Ask 1-3 questions per round (adaptive; only missing high-impact fields).
 - Question priority: `done_assertion` -> `target_route` -> `user_goal` -> optional inputs/scope.
-- Capture optional run-feel preferences when provided (for example: `fast`, `balanced`, `cinematic`, or explicit timing overrides).
+- Infer run feel and pacing automatically from user intent + discovered UI complexity.
+- Ask about run-feel preferences only when user intent explicitly asks for a style (for example: `fast`, `standard`, `cinematic`).
 - If host supports structured question-card requests, emit payloads from `references/question-card-spec.md`.
 - If structured cards are not supported, ask equivalent plain-language questions.
 - Track known/missing fields using `references/clarification-state.md`.
@@ -54,7 +62,8 @@ Rules for authored flow:
 - Deterministic steps only.
 - Prefer stable selectors (`data-testid`).
 - Include clear step IDs and assertions at key transitions.
-- Include optional pacing fields when useful for recording quality.
+- Always synthesize pacing fields (`preDelayMs`, `postDelayMs`, `mouseMoveMs`, `highlightMs`, `dwellMs`) for interaction-heavy steps to keep demos human-looking.
+- Model scroll risk during authoring. For below-fold or overflow-container targets, add stable preconditions (`wait_for` on section/container) before interaction steps.
 - Add `recorder_export` only when the user explicitly asks for export at run completion.
 - If clarification remains incomplete after 2 rounds, generate best-effort flow with explicit assumptions.
 
@@ -69,7 +78,8 @@ pnpm validate -- --flow artifacts/flow.json
 8. Emit deterministic runtime handoff for `studioflow-cli`.
 
 Write `artifacts/studioflow-cli-handoff.json` using `references/cli-handoff-spec.md`.
-- Include `runtimePacing` in handoff when run-feel preferences or timing overrides are known.
+- Always include `runtimePacing` in handoff, inferred from authored flow pacing and intent.
+- Always include `recorder` in handoff (`quicktime` or `screenstudio`), resolved from intent wording + defaults.
 
 9. Hand off execution to `studioflow-cli` immediately.
 

package/{skills → bundled/skills}/studioflow-investigate/references/artifact-spec.md

@@ -32,9 +32,15 @@ Flow steps may include pacing fields:
 - dwellMs
 - narrativeCheckpoint
 
+Authoring intelligence rules:
+- Prefer setting pacing fields for click/type/assert transition steps by default, not only on outliers.
+- Anticipate scroll-sensitive interactions (below fold, nested overflow containers) and add deterministic setup steps (`wait_for` container/section) before click/type actions.
+- Keep selectors stable (`data-testid`) and avoid positional selectors for scroll-sensitive regions.
+
 Recorder note:
 - Include `recorder_export` only when user explicitly asks to export at run completion.
 - Without `recorder_export`, StudioFlow stops recording and completes the run without export.
+- Recorder software selection is not encoded in `flow.json`; include it in `studioflow-cli-handoff.json` as `recorder`.
 
 ## Open-intent fallback note
 

package/{skills → bundled/skills}/studioflow-investigate/references/clarification-state.md

@@ -9,6 +9,7 @@ known:
   target_route: null
   user_goal: null
   done_assertion: null
+  recorder_backend: null
   data_input: []
   scope_limit: null
 missing:
@@ -27,8 +28,9 @@ risks: []
    - `target_route`
    - `user_goal`
    - `done_assertion`
-3. Do not exceed 2 rounds.
-4. If anchors are still missing after round 2:
+3. Resolve `recorder_backend` from explicit intent wording when present (`screenstudio` or `quicktime`), else default `quicktime`.
+4. Do not exceed 2 rounds.
+5. If anchors are still missing after round 2:
    - add explicit `assumptions`
    - keep `confidence: low`
    - generate best-effort deterministic `flow.json`
@@ -38,5 +40,6 @@ risks: []
 Include in final response:
 
 - `Resolved`: key anchors and selected values
+- `Recorder`: selected backend (`quicktime` or `screenstudio`)
 - `Assumptions`: any inferred defaults
 - `Confidence`: `high|medium|low`

package/{skills → bundled/skills}/studioflow-investigate/references/cli-handoff-spec.md

@@ -13,11 +13,12 @@ Path:
   "version": 1,
   "intentSummary": "Record only onboarding + CRM in Demo Lab",
   "flowPath": "artifacts/flow.json",
+  "recorder": "screenstudio",
   "baseUrl": "http://localhost:4280",
   "startCommand": "pnpm dev:demo-lab",
   "healthPath": "/",
   "runtimePacing": {
-    "profile": "balanced",
+    "profile": "standard",
     "cursorMoveMs": 430,
     "cursorHighlightMs": 170,
     "typingDelayMs": 55,
@@ -37,12 +38,15 @@ Path:
 - `version`: integer, currently `1`.
 - `intentSummary`: concise run label for CLI `--intent`.
 - `flowPath`: deterministic artifact path. Default: `artifacts/flow.json`.
+- `recorder`: recorder backend used by CLI `--recorder`.
+  - Allowed values: `quicktime`, `screenstudio`.
+  - Selection rule: if user explicitly requests Screen Studio/QuickTime, preserve that; otherwise default `quicktime`.
 - `baseUrl`: runtime host URL.
 - `startCommand`: command used when app is not already healthy.
 - `healthPath`: health probe path used by runtime.
-- `runtimePacing`: optional runtime timing overrides.
+- `runtimePacing`: required runtime timing overrides derived from authored flow pacing.
   - Allowed fields: `profile`, `cursorMoveMs`, `cursorHighlightMs`, `typingDelayMs`, `clickPulseMs`, `stepPreDelayMs`, `stepPostDelayMs`, `stepDwellMs`.
-  - `profile` values: `fast`, `balanced`, `cinematic`.
+  - `profile` values: `fast`, `standard`, `cinematic`.
 - `notes`: optional operator notes.
 
 ## Invocation contract
@@ -50,7 +54,7 @@ Path:
 When handoff artifact is written, immediately invoke `studioflow-cli` (or equivalent runtime workflow in same agent) to execute:
 
 1. `pnpm validate -- --flow <flowPath>`
-2. `pnpm demo -- --flow <flowPath> --intent "<intentSummary>" --base-url <baseUrl> --start-command "<startCommand>" --health-path <healthPath>`
-3. If `runtimePacing` exists, set matching `STUDIOFLOW_*` env vars on the demo command.
+2. `pnpm demo -- --flow <flowPath> --intent "<intentSummary>" --recorder <recorder> --base-url <baseUrl> --start-command "<startCommand>" --health-path <healthPath>`
+3. Set matching `STUDIOFLOW_*` env vars from `runtimePacing` on the demo command.
 
 Do not ask the user to translate the handoff into commands.