screenci 0.0.17 → 0.0.18

package/skills/screenci/SKILL.md

@@ -1,16 +1,28 @@
 ---
 name: screenci
-description: Record ScreenCI videos in an already-initialized project by editing `.video.ts` files and running the Screenci workflow.
+description: Create, show, and guide with ScreenCI videos in an already-initialized project by editing `.video.ts` files and running the Screenci workflow.
 allowed-tools:
   - Bash(screenci:*)
   - Bash(npx:*)
   - Bash(npm:*)
 ---
 
-# ScreenCI
+# ScreenCI Video and Guide Skill
 
 Use this skill when the task is about ScreenCI video recording workflows in an existing project, or updating `.video.ts` files and `screenci.config.ts`.
 
+Trigger this skill when the user asks to:
+
+- create a video
+- show a flow as a video
+- create a guide/demo video
+
+Routing rules:
+
+- If the user provides a URL, always use the `playwright-cli` skill first to inspect the real page flow and selectors before editing the ScreenCI script.
+- If the user provides source code for the target page/component, that usually means browser exploration is not required first.
+- If the request is only about application/source-code changes (not recording or `.video.ts` updates), do not use this skill.
+
 ## Quick Start
 
 Assume the project is already initialized. Add or edit video scripts in `videos/`.
@@ -19,7 +31,7 @@ If you are creating new videos, remove the starter `videos/example.video.ts` fil
 
 ```bash
 # iterate locally without recording
-npx screenci dev
+npx screenci test --ui
 
 # verify repeatedly until green
 npx screenci test
@@ -42,13 +54,14 @@ ScreenCI uses Playwright-style `.video.ts` files and adds recording-specific hel
 **Every video MUST follow these conventions:**
 
 1. **Narration on every video (required, no exceptions)** — always define `createNarration({ ... })` and add narration to every `.video.ts` file. Videos without narration are not acceptable.
-2. **Hide initial setup** — wrap authentication, navigation to the starting page, loading spinners, and any other non-demo boilerplate in `hide()` so they are cut from the final recording.
+2. **Hide initial setup** — the initial page load should almost always be wrapped in `hide()`. Keep authentication, navigation to the starting page, loading spinners, cookie banner dismissal, and any other non-demo boilerplate inside that hidden block so they are cut from the final recording.
 3. **Use autoZoom sparingly on large page areas** — add `autoZoom()` only for larger sections that benefit from camera guidance (e.g. a full form, a full dialog, or a broad list area). Keep usage sparse, and make sure each `autoZoom()` block includes multiple related interactions (typing, selecting, toggling, confirming, etc.), not just a single click.
+4. **End autoZoom before page changes** — it is better to let an `autoZoom()` block finish before a navigation/page change. Staying zoomed during navigation is confusing. Start a new `autoZoom()` block on the next page/section when needed.
 
 ## Command Notes
 
-- `screenci record` runs the recording flow. By default it uses Podman or Docker unless `--no-container` is used.
-- `screenci dev` runs Playwright in UI mode for fast iteration without screen capture.
+- `screenci record` runs the recording flow in Podman or Docker.
+- `screenci test --ui` runs Playwright in UI mode for fast iteration without screen capture.
 - `screenci retry` uploads the latest `.screenci` output when API configuration is available.
 
 ## Recording Workflow
@@ -57,7 +70,7 @@ ScreenCI uses Playwright-style `.video.ts` files and adds recording-specific hel
 2. Add or edit `.video.ts` files in `videos/`.
    Remove `videos/example.video.ts` if you are creating new videos and do not need the starter video.
    For narration, define `const narration = createNarration({ ... })` near the top of the file and trigger lines with `await narration.someKey` inside the test body.
-3. Run `npx screenci dev` to validate selectors and flow.
+3. Run `npx screenci test --ui` to validate selectors and flow.
 4. Run `npx screenci test` until it passes.
 5. Run `npx screenci record` to produce `.screenci/<video-name>/recording.mp4` and `data.json`.
 

package/skills/screenci/references/record.md

@@ -9,7 +9,6 @@ If you are creating new videos, remove the starter `videos/example.video.ts` fil
 
 ```bash
 npx screenci record
-npx screenci record --no-container
 npx screenci record -c screenci.config.ts
 ```
 
@@ -23,7 +22,6 @@ npx screenci record -c screenci.config.ts
 ## Runtime Behavior
 
 - By default, recording runs in Podman or Docker.
-- `--no-container` runs directly on the host.
 - Playwright arguments can be passed through after the command.
 - When API configuration and `SCREENCI_SECRET` are available, uploads may run after recording.
 
@@ -31,7 +29,7 @@ npx screenci record -c screenci.config.ts
 
 ```bash
 # first verify the flow
-npx screenci dev
+npx screenci test --ui
 
 # then record
 npx screenci record
@@ -48,7 +46,7 @@ npx screenci record # capture the final recording
 
 ## Required Conventions
 
-These are not optional — every `.video.ts` file must follow all three:
+These are not optional — every `.video.ts` file must follow all four:
 
 ### 1. Narration on every video (required, no exceptions)
 
@@ -56,12 +54,16 @@ Always add `createNarration({ ... })` to every video file. Videos without narrat
 
 ### 2. Hide initial setup
 
-Always wrap initial setup in `hide()`: login flows, navigation to the starting page, loading states, cookie banners, and any other boilerplate that is not part of the feature being demonstrated. If it is not the point of the video, hide it.
+Always wrap initial setup in `hide()`, especially the initial page load: login flows, navigation to the starting page, loading states, cookie banners, and any other boilerplate that is not part of the feature being demonstrated. It is also a good place to click away cookie banners so they never appear in the final video. If it is not the point of the video, hide it.
 
 ### 3. Use autoZoom sparingly on large page areas
 
 Add `autoZoom()` only for larger sections that benefit from camera guidance — for example a full form, full dialog, or broad list area. Use `autoZoom()` sparingly, and ensure each block includes multiple related interactions (typing, selecting, toggling, confirming, etc.), not just a single click.
 
+### 4. End autoZoom before page changes
+
+Let each `autoZoom()` block complete before navigation/page changes. Staying zoomed during a route transition is confusing for viewers. After the new page is ready, start a new `autoZoom()` block for that page section if needed.
+
 ## Constraints
 
 - ScreenCI enforces single-worker recording behavior.