screencast-axi 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Valentyn Morenko
+
+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,555 @@
+# screencast-axi
+
+Record a scripted browser workflow as a watchable clip: a drawn cursor, burnt-in captions, and
+mp4 + webm + a poster out the other end. Built to [AXI](https://github.com/kunchenguid/axi)
+conventions, so an agent can drive it as comfortably as a person can.
+
+<picture>
+  <source srcset="docs/demo.anim.webp" type="image/webp">
+  <img src="docs/demo.gif" alt="Three acts: a prompt asking for a clip, the scenario that gets written, and the recording it produces in a real app." width="640">
+</picture>
+
+<sup>The ask, the scenario that came back, and the take it produced - itself recorded by this tool,
+from [`demo/scenarios/demo.ts`](demo/scenarios/demo.ts). Re-record it with `pnpm demo`.</sup>
+
+> **Status: 0.x and not yet published.** The recorder works end to end; the command surface is
+> still growing. See [Roadmap](#roadmap).
+
+## What the tool does
+
+The clips below were produced by this repo - the scenarios are in
+[`demo/scenarios/`](demo/scenarios/), and `pnpm demo:usecases` re-records them.
+
+### Point it at any site and describe the workflow
+
+There is no integration to write: no plugin for the site, no fixtures, no test IDs added to the
+page. A scenario names what to do, and the recorder does it.
+
+> _"Record a clip of searching Wikipedia for Ada Lovelace, opening the article, and jumping to the
+> Work section. Around ten seconds."_
+
+<picture>
+  <source srcset="docs/usecase-anysite.anim.webp" type="image/webp">
+  <img src="docs/usecase-anysite.gif" alt="Searching Wikipedia, watching live suggestions arrive, opening the article and jumping to a section." width="480">
+</picture>
+
+<sup>The whole scenario is [50 lines](demo/scenarios/anysite.ts), most of it narration and
+comments.</sup>
+
+### Records a sign-in, or skips past one
+
+> _"Sign in to our staging dashboard and record a 15 second clip of creating an invoice. I will
+> do the login myself."_
+
+A login is an ordinary workflow as far as the recorder is concerned: a field, a field, a button.
+It is worth filming, because it is the part of a product most demos skip.
+
+<picture>
+  <source srcset="docs/usecase-login.anim.webp" type="image/webp">
+  <img src="docs/usecase-login.gif" alt="A real login form being filled in and submitted, landing on the page behind it." width="460">
+</picture>
+
+For a real app you usually want the opposite - the clip should open already through the door
+rather than spend its first seconds on a form. So signing in becomes a one-time human step, and
+this is what that looks like from your side:
+
+> **A real Chrome window opens on your screen, at the site you are recording.**
+> Sign in there however that site wants: password, SSO, a magic link, two-factor, a passkey.
+> Then **close the window** - closing it is the signal that you are done.
+> Nothing is ever typed into the terminal, and no credential passes through this package. The
+> session is saved into a Chrome profile on your machine, and every later take reuses it.
+
+An agent can open that window for you rather than making you retype a command, but it cannot sign
+in for you and will not try: without `--interactive` it stops and says a person is needed, and it
+refuses outright where no window could appear, such as a headless CI box. The wait is bounded, so
+it can never hang.
+
+For a login you can script, an `AuthStrategy` object in the config does the same job in typed code
+([worked example](demo/auth/form-login.ts)). Either way it runs before recording starts, so none
+of it lands in the clip.
+
+### Renders at phone and tablet viewports
+
+> _"Record our onboarding on an iPhone, portrait, about fifteen seconds - I want it for the app
+> store listing."_
+
+A device preset does more than set a width. Its `isMobile` and `hasTouch` flags decide whether the
+site's own `@media (hover: none)` and touch rules apply at all, and it carries the right user
+agent - so this is the mobile layout the site actually serves, not a desktop squeezed narrow.
+Playwright ships 140+ presets; `--viewport 390x844` covers the rest.
+
+<picture>
+  <source srcset="docs/usecase-mobile.anim.webp" type="image/webp">
+  <img src="docs/usecase-mobile.gif" alt="The same workflow recorded in a portrait phone viewport." width="240">
+</picture>
+
+<sup>The video is captured at the CSS viewport - 390x664 here - because Playwright composites the
+page into the video canvas without scaling up. `deviceScaleFactor` still changes how the page
+renders and which images it picks, but not the resolution of the recording.</sup>
+
+### Shows you what it is doing
+
+A scenario is arbitrary code driving a real browser, often one signed into your own account, so
+"is this safe to run" deserves a better answer than "read the TypeScript".
+
+```sh
+screencast-axi rehearse <id> --headed
+```
+
+`--headed` runs it in a real window instead of hidden, so you can watch the whole thing. It does
+not change the output - the clip is identical either way - so it costs nothing but the window.
+
+Watching answers the question once, though, and only while you sit there. So a rehearsal also
+prints what it did, in a form you can read before running, diff after an edit, and keep:
+
+```
+$ screencast-axi rehearse usecase-login
+
+rehearsed: usecase-login
+duration_s: 10.8
+pace: 1
+viewport: 900x540
+steps[4]: A real login form,"Username, then password",Submitted for real,And the page behind it
+hosts[1]: the-internet.herokuapp.com
+performed[10]:
+  - at_s: 0.2
+    did: goto
+    target: "https://the-internet.herokuapp.com/login"
+  - at_s: 1.8
+    did: waitFor
+    target: #username
+  - at_s: 1.8
+    did: step
+    detail: A real login form
+  - at_s: 2.9
+    did: step
+    detail: "Username, then password"
+  - at_s: 2.9
+    did: type
+    target: #username
+    detail: tomsmith
+  - at_s: 4.3
+    did: type
+    target: #password
+    detail: •••••••• (20 chars)
+  - at_s: 7.1
+    did: step
+    detail: Submitted for real
+  - at_s: 7.1
+    did: click
+    target: "button[type=submit]"
+  - at_s: 8.2
+    did: waitFor
+    target: h2
+  - at_s: 8.8
+    did: step
+    detail: And the page behind it
+```
+
+Note the password: a field the log would otherwise leak records its shape and nothing else.
+
+`hosts` is the short answer to where it went, taken from the pages the browser actually reached -
+so a redirect or a navigation buried in `setup()` shows up too. A list of one host reads very
+differently from a list of nine.
+
+### Aims a clip at a length
+
+```sh
+screencast-axi record tour --duration 30s
+```
+
+One measuring pass, then it solves for the pace that lands near the target. A take is
+`fixed + pace x scalable` - the site's own waits do not get slower because the recorder does - so
+the solve uses the measured split rather than assuming everything scales. Pace is clamped to a
+watchable range, and a target outside it is reported rather than obeyed.
+
+### Emits what the destination needs
+
+mp4 and webm every time, plus a poster frame. `--gif` and `--webp` add looping images for the
+places a `<video>` does not render - a README, an npm page, an email. Every image on this page is
+one of them. See [Output formats](#output-formats) for what each costs.
+
+Drag-and-drop is handled too, including the HTML5 protocol that Chromium will not synthesise from
+mouse events - the interaction most likely to look like a teleport if a recorder cuts corners.
+
+## Why a script, not a screen recorder
+
+A screencast is a performance with a script, not a recording of work being done. What makes one
+watchable is a set of constants - a settle before each click, an eased pointer glide, a consistent
+hold on each caption - and constants only help if you can run the same thing again and get the
+same thing back. A scenario file survives a product change, gets reviewed in a pull request, and
+can be re-cut at a different length without re-deciding anything.
+
+## Quick start
+
+No config needed. Point it at any site:
+
+```sh
+npx -y screencast-axi scaffold product-tour --url https://example.com
+# fill in the run() body
+npx -y screencast-axi rehearse ./scenarios/product-tour.ts
+npx -y screencast-axi record   ./scenarios/product-tour.ts
+```
+
+`rehearse` runs the scenario without encoding, so a stale selector surfaces in seconds rather than
+a minute - and the failure comes back with the URL it reached, a screenshot, and what each part of
+the selector actually matched.
+
+A scenario is TypeScript:
+
+```ts
+import { defineScenario } from "screencast-axi";
+
+export default defineScenario({
+  id: "product-tour",
+  title: "A three-stop tour",
+  description: "The pages that matter, in order.",
+  steps: ["Where the work lives", "How it gets organised", "And what comes out"],
+
+  async run(d) {
+    await d.tour([
+      { path: "/", step: 0, scroll: 0.6 },
+      { path: "/features", step: 1, scroll: 0.5 },
+      { path: "/pricing", step: 2 },
+    ]);
+  },
+});
+```
+
+Each line in `steps` goes on screen once, in order. The same array becomes the burnt-in caption
+and the manifest's step list, so the written workflow cannot drift from the recorded one - a take
+that skips a line fails.
+
+## Install
+
+The skill is installed from GitHub; the CLI is pulled on demand, so there is nothing global:
+
+```sh
+npx skills add Valzon/screencast-axi --skill screencast-axi -g
+```
+
+## Prerequisites
+
+| Piece       | Required | How it is found                                                      |
+| ----------- | -------- | -------------------------------------------------------------------- |
+| Node        | >= 20    |                                                                      |
+| Chromium    | yes      | Playwright downloads it                                              |
+| `ffmpeg`    | yes      | `$SCREENCAST_FFMPEG`, then an installed `ffmpeg-static`, then `PATH` |
+| WebP poster | optional | ffmpeg's `libwebp`, else `cwebp`, else a PNG poster                  |
+
+ffmpeg is not bundled: it is 80MB+ per platform, and _which_ build you have matters - many builds
+(Homebrew's among them) ship without `libwebp`, which is why the poster has a fallback chain
+rather than one hard requirement. If you would rather not install it system-wide,
+`pnpm add -D ffmpeg-static` and the cascade finds it.
+
+**Platforms:** macOS and Linux are tested, including in CI. Windows is intended to work but is
+**unverified** - the known risks are argument quoting in spawned ffmpeg filter strings, path
+separators inside those arguments, and Chrome's lock on a persistent profile directory.
+
+## Recording a page behind a login
+
+The strategy that needs no code for the site you are recording is `profileAuth()`. A person runs
+this once:
+
+```sh
+npx -y screencast-axi auth login --interactive
+```
+
+A browser opens, they sign in however that site wants - OAuth, SSO, a magic link, two-factor - and
+close the window. The session lives in a persistent Chrome profile and every take reuses it. No
+credential is handled by this package.
+
+`auth login` never reads stdin, so an agent can open the window on the user's screen rather than
+making them retype a command. It cannot hang: the wait is bounded, and it refuses up front where
+no window could appear.
+
+Also shipped: `storageStateAuth({ path })` for a portable session file, and
+`basicAuth({ username, password })` for staging environments. Anything else is an `AuthStrategy`
+object written in the config - typed and debuggable rather than a shelled-out script.
+
+> A scenario that creates or drags something **writes to whatever it is pointed at**. Prefer
+> read-only scenarios against production, or point at staging.
+
+## Seeing what a scenario does
+
+A scenario is arbitrary code driving a real browser, often one signed into your own account, so
+"what will this actually do" deserves a better answer than "read the TypeScript". Two:
+
+```sh
+screencast-axi rehearse <id>            # prints every action it took
+screencast-axi rehearse <id> --headed   # and shows you it happening
+```
+
+A rehearsal prints `performed` - every goto, click, typed value, drag and scroll, in order, with
+timings - and `hosts`, the short answer to where the script went. `--headed` opens a real window
+and does not change the output; the clip is identical either way.
+
+## Output formats
+
+Every take produces an mp4, a webm and a poster. Looping images are opt-in with `--gif` and
+`--webp`, for the places a `<video>` does not render - a README, an npm page, an email.
+
+Measured on a real 16.7s app screencast, all at 800px and 15fps:
+
+| Format        | Size     | vs mp4 |
+| ------------- | -------- | ------ |
+| mp4 (h264)    | 182 KB   | 1x     |
+| animated WebP | 944 KB   | 5.2x   |
+| GIF           | 2,034 KB | 11.2x  |
+
+Prefer WebP where it renders: same content, roughly half the bytes, full colour rather than a
+256-entry palette. Quality is not the deciding factor for flat app UI - 192 colours plus dithering
+keeps small text legible - but a GIF has no controls, no seeking, no poster frame, cannot be
+paused, and ignores `prefers-reduced-motion`. It is an export, not a storage format.
+
+## Configuration
+
+Optional. `screencast.config.ts` at the repo root, found by walking up from the working directory:
+
+```ts
+import { defineConfig, profileAuth } from "screencast-axi";
+
+export default defineConfig({
+  baseUrl: "http://localhost:3000",
+  scenarios: ["scenarios/*.ts"],
+  outDir: "public/demos",
+  viewport: { width: 1440, height: 900 },
+
+  browser: { profileDir: ".screencast/profile" },
+  auth: profileAuth({ signedInSelector: "[data-testid=user-menu]" }),
+
+  overlay: {
+    accent: "#4f46e5",
+    // Page chrome that should not end up in the footage.
+    hideSelectors: ["#cookie-banner", "nextjs-portal"],
+  },
+});
+```
+
+Relative paths resolve against the config file, never the shell's working directory, so a command
+means the same thing from anywhere in a repo.
+
+## Mobile, and aiming at a length
+
+```sh
+screencast-axi record tour --device "iPhone 13" --orientation portrait --duration 20s
+```
+
+Device presets come from Playwright's registry, so a phone clip is captured at its real device
+pixels rather than its CSS viewport - the difference between readable UI text and a smear.
+
+`--duration` runs one measuring pass, then solves for the pace that lands near the target. A take
+is `fixed + pace x scalable`: the site's own waits do not get slower because the recorder does, so
+the solve uses the measured split rather than assuming everything scales.
+
+## Reading the manifest
+
+Every take writes `manifest.json` beside the clips. A site can read it at build time without
+pulling in Playwright or a browser:
+
+```ts
+import { readManifest, clipFilesFor } from "screencast-axi/manifest";
+```
+
+That entry point has no runtime dependencies at all.
+
+## Command reference
+
+<!-- reference:start -->
+
+Every command takes `--help`. Flags always come after the command:
+`screencast-axi <command> [args] [flags]`. An unknown flag is a usage error rather than
+something quietly ignored.
+
+#### `init`
+
+Write a config, a scenarios directory and a gitignore entry.
+
+```sh
+screencast-axi init
+```
+
+| Flag          | What it does                      |
+| ------------- | --------------------------------- |
+| `--out <dir>` | Where clips should be written.    |
+| `--url <url>` | Base URL for the site you record. |
+| `--force`     | Overwrite an existing config.     |
+
+#### `scaffold`
+
+Write a scenario skeleton so the boilerplate is never what goes wrong.
+
+```sh
+screencast-axi scaffold <id>
+```
+
+| Flag              | What it does                              |
+| ----------------- | ----------------------------------------- |
+| `--url <url>`     | Base URL the scenario opens.              |
+| `--title <text>`  | Human title for the clip.                 |
+| `--dir <path>`    | Where to write it.                        |
+| `--tour <value>`  | Write an n-stop page walkthrough instead. |
+| `--device <name>` | Playwright device preset.                 |
+
+#### `rehearse`
+
+Run a scenario without recording, and print every action it took.
+
+```sh
+screencast-axi rehearse <id|path...>
+```
+
+| Flag                | What it does                              |
+| ------------------- | ----------------------------------------- |
+| `--config <path>`   | Path to a config file.                    |
+| `--base-url <url>`  | Override the scenario's base URL.         |
+| `--pace <value>`    | Speed multiplier; lower is faster.        |
+| `--device <name>`   | Playwright device preset.                 |
+| `--viewport <WxH>`  | Explicit size, e.g. 390x844.              |
+| `--orientation <o>` | portrait or landscape.                    |
+| `--headed`          | Watch it happen in a real browser window. |
+| `--auth <name>`     | Named auth strategy from the config.      |
+| `--no-auth`         | Record signed out.                        |
+
+#### `record`
+
+Run a scenario for real and encode the clip.
+
+```sh
+screencast-axi record <id|path...>
+```
+
+| Flag                   | What it does                                                          |
+| ---------------------- | --------------------------------------------------------------------- |
+| `--config <path>`      | Path to a config file.                                                |
+| `--base-url <url>`     | Override the scenario's base URL.                                     |
+| `--pace <value>`       | Speed multiplier; lower is faster.                                    |
+| `--device <name>`      | Playwright device preset.                                             |
+| `--viewport <WxH>`     | Explicit size, e.g. 390x844.                                          |
+| `--orientation <o>`    | portrait or landscape.                                                |
+| `--headed`             | Watch it happen in a real browser window.                             |
+| `--auth <name>`        | Named auth strategy from the config.                                  |
+| `--no-auth`            | Record signed out.                                                    |
+| `--duration <30s>`     | Aim for this length, e.g. 30s (measures first, then solves for pace). |
+| `--out <dir>`          | Output directory.                                                     |
+| `--all`                | Record every scenario the config lists.                               |
+| `--full`               | Include the full action log.                                          |
+| `--gif`                | Also emit a looping GIF.                                              |
+| `--webp`               | Also emit a looping WebP (half a GIF's size).                         |
+| `--loop-width <value>` | Width of the looping formats.                                         |
+| `--loop-fps <value>`   | Frame rate of the looping formats.                                    |
+| `--keep-raw`           | Keep the raw capture for inspection.                                  |
+
+#### `list`
+
+Every scenario, with what needs re-shooting.
+
+```sh
+screencast-axi list
+```
+
+| Flag              | What it does                              |
+| ----------------- | ----------------------------------------- |
+| `--config <path>` | Path to a config file.                    |
+| `--full`          | Every field, not the four-column summary. |
+| `--stale`         | Only what needs re-shooting.              |
+| `--tag <name>`    | Filter by scenario tag. Repeatable.       |
+
+#### `show`
+
+One clip in full: files, sizes, narration, when it was shot.
+
+```sh
+screencast-axi show <id>
+```
+
+| Flag              | What it does                   |
+| ----------------- | ------------------------------ |
+| `--config <path>` | Path to a config file.         |
+| `--full`          | Include untruncated step text. |
+
+#### `check`
+
+Cross-reference the manifest, the scenarios and the files on disk.
+
+```sh
+screencast-axi check
+```
+
+| Flag              | What it does                                                    |
+| ----------------- | --------------------------------------------------------------- |
+| `--config <path>` | Path to a config file.                                          |
+| `--fix-orphans`   | Delete manifest entries and media with no scenario behind them. |
+
+#### `doctor`
+
+Check everything a recording needs, in one pass.
+
+```sh
+screencast-axi doctor
+```
+
+| Flag              | What it does           |
+| ----------------- | ---------------------- |
+| `--config <path>` | Path to a config file. |
+
+#### `setup`
+
+Install the browser; name anything you must install yourself.
+
+```sh
+screencast-axi setup
+```
+
+| Flag              | What it does                        |
+| ----------------- | ----------------------------------- |
+| `--browsers-only` | Install Chromium and stop.          |
+| `--scope <s>`     | For `setup hooks`: user or project. |
+
+#### `auth`
+
+Sign in by hand once, or check the saved session still works.
+
+```sh
+screencast-axi auth login|check [name]
+```
+
+| Flag                  | What it does                                                 |
+| --------------------- | ------------------------------------------------------------ |
+| `--config <path>`     | Path to a config file.                                       |
+| `--base-url <url>`    | Site to sign in to.                                          |
+| `--interactive`       | Required for `login`: opens a real browser.                  |
+| `--save-state <path>` | Write a Playwright storage state here as well.               |
+| `--headed`            | Show the browser for `check`.                                |
+| `--wait <5m>`         | How long `login` waits for the window to close (default 5m). |
+
+#### `guide`
+
+Topic-sized guidance, pulled one topic at a time.
+
+```sh
+screencast-axi guide [topic]
+```
+
+_No flags._
+<!-- reference:end -->
+
+## Roadmap
+
+Publishing to npm. The command surface is complete; `setup hooks` is declared but not implemented
+and says so rather than pretending.
+
+## Contributing
+
+```sh
+pnpm install
+pnpm build && pnpm test && pnpm typecheck && pnpm format
+```
+
+`skills/screencast-axi/SKILL.md` is generated from `src/skill.ts` - edit the generator, run
+`pnpm build:skill`, and commit the result. CI fails if the two drift, and the generator throws if
+the stub grows past its character cap.
+
+## License
+
+MIT

package/dist/bin/screencast-axi.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/screencast-axi.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { tryFastPath } from "axi-sdk-js/fast-path";
+import { VERSION } from "../src/version.js";
+// `screencast-axi --help | head` closes the pipe early, and an unhandled EPIPE
+// turns that into a stack trace. Piping output somewhere that stops reading is
+// ordinary shell use, not an error worth reporting.
+process.stdout.on("error", (error) => {
+    if (error.code === "EPIPE")
+        process.exit(0);
+    throw error;
+});
+if (!tryFastPath(process.argv.slice(2), { version: VERSION })) {
+    const { main } = await import("../src/cli.js");
+    await main();
+}
+//# sourceMappingURL=screencast-axi.js.map

package/dist/bin/screencast-axi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"screencast-axi.js","sourceRoot":"","sources":["../../bin/screencast-axi.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAE5C,+EAA+E;AAC/E,+EAA+E;AAC/E,oDAAoD;AACpD,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAA4B,EAAE,EAAE;IAC1D,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO;QAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC5C,MAAM,KAAK,CAAC;AACd,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;IAC9D,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,CAAC;IAC/C,MAAM,IAAI,EAAE,CAAC;AACf,CAAC"}

package/dist/src/auth/strategies.d.ts

@@ -0,0 +1,54 @@
+import type { AuthStrategy } from "./types.js";
+/** Signed-out. The default, and correct for most public surfaces. */
+export declare function noAuth(): AuthStrategy;
+export interface ProfileAuthOptions {
+    /** Where to land after signing in, so `auth check` can prove it worked. */
+    readonly landingPath?: string;
+    /** Something only a signed-in page renders. The strongest check available. */
+    readonly signedInSelector?: string;
+    /**
+     * Cookie the app sets once its own session is live.
+     *
+     * `name=value` checks the value too. Presence alone is a weak test: plenty
+     * of sites set the same cookie to a signed-out value (GitHub sends
+     * `logged_in=no`), so a name-only check quietly passes when it should not.
+     */
+    readonly signedInCookie?: string;
+    readonly label?: string;
+}
+/**
+ * Sign in once by hand; every take afterwards reuses the session.
+ *
+ * This is the strategy that makes the tool work on a site nobody wrote a
+ * strategy for. The browser opens, a person signs in however that site wants -
+ * OAuth, SSO, a magic link, two-factor - and closes the window. The session
+ * lives in the persistent Chrome profile, so no code here has to know anything
+ * about how that site authenticates, and no credential is ever handled by this
+ * package.
+ *
+ * It needs `browser.profileDir` set, since a persistent profile is the thing
+ * doing the remembering.
+ */
+export declare function profileAuth(options?: ProfileAuthOptions): AuthStrategy;
+export interface StorageStateOptions {
+    /** Playwright storage-state JSON. Relative paths anchor to the config. */
+    readonly path: string;
+    readonly landingPath?: string;
+    readonly signedInSelector?: string;
+}
+/**
+ * A saved Playwright session file.
+ *
+ * Portable and CI-friendly in a way a Chrome profile is not: it is one JSON
+ * file that can be produced once and committed to a secret store. Needs an
+ * isolated context, so it cannot be combined with `browser.profileDir`.
+ */
+export declare function storageStateAuth(options: StorageStateOptions): AuthStrategy;
+export interface BasicAuthOptions {
+    readonly username: string;
+    readonly password: string;
+}
+/** HTTP basic auth, which is how most staging environments are gated. */
+export declare function basicAuth(options: BasicAuthOptions): AuthStrategy;
+/** Splits `name=value` into its parts; a bare name means "any value". */
+export declare function splitCookie(spec: string): [name: string, value: string | undefined];