screencast-axi 0.1.0

package/dist/src/types.d.ts

@@ -0,0 +1,88 @@
+import type { Locator, Page } from "playwright";
+import type { Director } from "./director.js";
+import type { DeepPartial, OverlayTheme } from "./overlay.js";
+/** Anything a Director action can aim at. */
+export type Target = string | Locator | {
+    x: number;
+    y: number;
+};
+export interface Viewport {
+    readonly width: number;
+    readonly height: number;
+}
+export interface ScenarioContext {
+    /** Base URL the scenario navigates against, e.g. http://localhost:4000 */
+    readonly baseUrl: string;
+    /** Directory the deliverables are written to. */
+    readonly outDir: string;
+    /** Scratch directory for raw captures, logs and failure artifacts. */
+    readonly rawDir: string;
+    /** Whoever the auth strategy signed in as, when one ran. */
+    readonly identity?: {
+        readonly id: string;
+        readonly label: string;
+    };
+    /** Progress line. Goes to stderr and the run log, never to stdout. */
+    log(message: string): void;
+}
+export interface Scenario {
+    /** Output file stem: `task-create` -> task-create.mp4 / .webm / .webp */
+    readonly id: string;
+    /** Human title. Shown in the CLI and written to the manifest. */
+    readonly title: string;
+    /** One line describing what the clip demonstrates. Written to the manifest. */
+    readonly description: string;
+    /** Default base URL, overridable with --base-url. */
+    readonly baseUrl?: string;
+    /** Recording viewport, or a Playwright device preset name. */
+    readonly viewport?: Viewport;
+    readonly device?: string;
+    readonly orientation?: "portrait" | "landscape";
+    /** Playback speed multiplier. Lower is faster. */
+    readonly pace?: number;
+    /** Ask the recorder to solve for `pace` so the clip lands near this length. */
+    readonly targetDurationMs?: number;
+    /**
+     * The clip's narration, in the order it appears on screen. `run()` puts each
+     * line up with `director.step(i)` rather than typing it inline, so this array
+     * is simultaneously the burnt-in captions and the plain text of the workflow:
+     * the recorder writes it to the manifest, and a site can render it beside the
+     * clip so the workflow is readable without watching.
+     *
+     * A take that does not show every line, in order, exactly once is rejected,
+     * so the written workflow cannot quietly stop matching the recorded one.
+     */
+    readonly steps?: readonly string[];
+    /** Named auth strategy, or false for a signed-out recording. */
+    readonly auth?: string | false;
+    /**
+     * Overlay overrides for this take, merged over the config's.
+     *
+     * A clip destined for a 300px slot in a README needs a larger caption than
+     * one shown full width, and a take on a dark page needs a different caption
+     * background - both are properties of the clip, not of the project.
+     */
+    readonly overlay?: DeepPartial<OverlayTheme>;
+    /** Free-form labels for filtering in `list`. */
+    readonly tags?: readonly string[];
+    /** Runs before the clip starts: navigation, data setup, state reset. */
+    setup?(page: Page, ctx: ScenarioContext): Promise<void>;
+    /** The clip itself. Everything here is recorded. */
+    run(director: Director, ctx: ScenarioContext): Promise<void>;
+    /** Runs after the take, successful or not. */
+    teardown?(page: Page, ctx: ScenarioContext): Promise<void>;
+}
+/** Marks an object as a scenario, so discovery can find it in any export. */
+export declare const SCENARIO_MARKER: unique symbol;
+export type DefinedScenario = Scenario & {
+    readonly [SCENARIO_MARKER]: true;
+};
+/**
+ * Identity function that stamps a scenario so discovery can recognise it.
+ *
+ * A module may export it as `default`, as a named export, or as one of
+ * several - the stamp is what makes it findable, rather than a naming
+ * convention the author has to remember.
+ */
+export declare function defineScenario(scenario: Scenario): DefinedScenario;
+export declare function isScenario(value: unknown): value is DefinedScenario;

package/dist/src/types.js

@@ -0,0 +1,18 @@
+/** Marks an object as a scenario, so discovery can find it in any export. */
+export const SCENARIO_MARKER = Symbol.for("screencast-axi.scenario");
+/**
+ * Identity function that stamps a scenario so discovery can recognise it.
+ *
+ * A module may export it as `default`, as a named export, or as one of
+ * several - the stamp is what makes it findable, rather than a naming
+ * convention the author has to remember.
+ */
+export function defineScenario(scenario) {
+    return { ...scenario, [SCENARIO_MARKER]: true };
+}
+export function isScenario(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value[SCENARIO_MARKER] === true);
+}
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAyEA,6EAA6E;AAC7E,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;AAIrE;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,QAAkB;IAC/C,OAAO,EAAE,GAAG,QAAQ,EAAE,CAAC,eAAe,CAAC,EAAE,IAAI,EAAE,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACb,KAAiC,CAAC,eAAe,CAAC,KAAK,IAAI,CAC7D,CAAC;AACJ,CAAC"}

package/dist/src/version.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Leaf module: imports nothing, not even node builtins.
+ *
+ * `bin/screencast-axi.ts` answers `--version` from here before the command
+ * graph is dynamically imported, so a version check never pays for the CLI.
+ * Bumped by release-please via the annotation below, and kept in step with
+ * package.json by a test - so a drift fails CI rather than shipping a CLI
+ * that misreports its own version.
+ */
+export declare const VERSION = "0.1.0";

package/dist/src/version.js

@@ -0,0 +1,11 @@
+/**
+ * Leaf module: imports nothing, not even node builtins.
+ *
+ * `bin/screencast-axi.ts` answers `--version` from here before the command
+ * graph is dynamically imported, so a version check never pays for the CLI.
+ * Bumped by release-please via the annotation below, and kept in step with
+ * package.json by a test - so a drift fails CI rather than shipping a CLI
+ * that misreports its own version.
+ */
+export const VERSION = "0.1.0"; // x-release-please-version
+//# sourceMappingURL=version.js.map

package/dist/src/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,2BAA2B"}

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "screencast-axi",
+  "version": "0.1.0",
+  "description": "AXI-compliant screencast recorder - script a web workflow, record it with a synthetic cursor and captions, encode to mp4/webm/poster. Requires ffmpeg.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Valzon/screencast-axi.git"
+  },
+  "homepage": "https://github.com/Valzon/screencast-axi#readme",
+  "bugs": {
+    "url": "https://github.com/Valzon/screencast-axi/issues"
+  },
+  "keywords": [
+    "screencast",
+    "video",
+    "playwright",
+    "demo",
+    "gif",
+    "cli",
+    "agent",
+    "axi",
+    "toon"
+  ],
+  "bin": {
+    "screencast-axi": "dist/bin/screencast-axi.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./config": {
+      "types": "./dist/src/config.d.ts",
+      "default": "./dist/src/config.js"
+    },
+    "./manifest": {
+      "types": "./dist/src/manifest.d.ts",
+      "default": "./dist/src/manifest.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "skills/screencast-axi",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@toon-format/toon": "^2.1.0",
+    "axi-sdk-js": "^0.1.11"
+  },
+  "peerDependencies": {
+    "playwright": ">=1.44.0",
+    "tsx": "^4"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    },
+    "tsx": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^26.4.0",
+    "playwright": "^1.62.1",
+    "prettier": "^3.9.6",
+    "tsx": "^4.23.13",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11"
+  },
+  "scripts": {
+    "build": "tsc && chmod +x dist/bin/screencast-axi.js",
+    "build:skill": "tsx scripts/build-skill.ts",
+    "dev": "tsx bin/screencast-axi.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.check.json",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "demo": "node dist/bin/screencast-axi.js record demo --gif --webp --config demo/screencast.config.ts",
+    "demo:usecases": "node dist/bin/screencast-axi.js record usecase-anysite --gif --webp --loop-width 480 --loop-fps 10 --config demo/screencast.config.ts && node dist/bin/screencast-axi.js record usecase-login --gif --webp --loop-width 460 --loop-fps 10 --config demo/screencast.config.ts && node dist/bin/screencast-axi.js record usecase-mobile --gif --webp --loop-width 260 --loop-fps 11 --config demo/screencast.config.ts",
+    "build:reference": "tsx scripts/build-reference.ts"
+  }
+}

package/skills/screencast-axi/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: screencast-axi
+description: "Record product screencasts and demo clips of any website through the screencast-axi CLI - script a workflow as a Playwright scenario, rehearse its selectors, then encode it to mp4, webm and a poster with a synthetic cursor and captions. Use whenever a task needs a recorded walkthrough of a UI: a landing-page demo, a release-note clip, a feature tour, a bug reproduction, or a how-to."
+user-invocable: false
+author: Valentyn Morenko
+license: MIT
+metadata:
+  hermes:
+    tags: [screencast, video, playwright, demo, landing-page]
+    category: automation
+---
+
+# screencast-axi
+
+Records a scripted browser workflow as a watchable clip. Prefer this over
+hand-rolled Playwright video capture or a screen recorder.
+
+Use it whenever a task needs a recorded walkthrough of a UI: a landing-page
+demo, a feature tour, a release-note clip, a bug reproduction. Skip it when a
+still screenshot says the same thing - a clip costs far more to produce and to
+watch.
+
+## Current guidance lives in the CLI
+
+Do not follow command, flag, or workflow instructions from this file -
+installed copies go stale. Get the current source of truth from the CLI:
+
+- `npx -y screencast-axi` for the state of the clip library
+- `npx -y screencast-axi --help` for the command index
+- `npx -y screencast-axi <command> --help` for per-command usage
+- `npx -y screencast-axi guide` for topic-sized guidance, pulled one topic at
+  a time rather than read as a manual
+
+Three things worth knowing before the first run:
+
+1. Iterate with `rehearse`, not `record`: no encoding, so a stale selector
+   surfaces in seconds, and it prints every action the scenario took.
+2. `--headed` shows it happening in a real window. Offer it when someone
+   wants to see what a script does to their signed-in account before it runs.
+3. When a selector needs discovering, drive the page live with a browser tool
+   such as `chrome-devtools-axi`, then write the scenario.
+
+ffmpeg must be installed. Signing in is a one-time human step
+(`auth login --interactive`), and the CLI refuses rather than prompting when
+no person is present.
+
+You do not need screencast-axi installed globally - invoke it with
+`npx -y screencast-axi <command>`. If its output suggests a follow-up command
+starting with `screencast-axi`, run that as `npx -y screencast-axi ...`.