autokap 1.0.0

package/assets/skill/SKILL.md

@@ -0,0 +1,575 @@
+---
+name: autokap-preset
+description: Generate AutoKap preset configurations for automated screenshot, clip, and video capture of web applications
+metadata:
+  author: AutoKap
+  version: 1.0.0
+---
+
+# AutoKap Preset Creation Skill
+
+## What is AutoKap
+
+AutoKap is a screenshot and video capture automation platform. It uses an AI agent inside a headless browser (Playwright) to navigate web applications and capture screenshots, clips (short animated GIFs/MP4s), or demo videos.
+
+A **preset** defines what to capture: which pages, which viewports/devices, which languages and themes, and how to navigate to the right state. A single preset can generate dozens of assets — one per combination of (page x target x language x theme).
+
+## Your Task
+
+You are being asked to create one or more AutoKap presets for the user's project. Your job is to:
+
+1. **Analyze the project** — look at the codebase (routes, pages, components, UI structure) to understand what the application looks like and how it's organized
+2. **Generate a complete preset configuration** in JSON format that AutoKap can import directly
+3. **Write precise navigation prompts** — the capture agent sees a screenshot + accessibility tree and follows your instructions to reach the right page state
+
+You know this project intimately. Use that knowledge to write prompts that are specific to the actual UI — reference real navigation elements, real page routes, real UI components.
+
+### Variants (CRITICAL)
+
+The prompt will include a "Variants" section specifying the exact `langs`, `themes`, and `targets` to use. **You MUST copy these values exactly into the preset config** — do not change, add, or remove any value. The user has already chosen their desired languages, themes, and device viewports. Your job is only to write the capture prompts (what to navigate to, what to capture).
+
+**Targets and mockupOptions**: The targets include `viewport`, `deviceFrame`, and `mockupOptions` (orientation, status bar, dock, safe areas, etc.) that the user has specifically configured. Copy each target object exactly as-is into the preset's `targets` array. Do not modify `mockupOptions` — if the user chose landscape orientation, keep landscape. If they configured a status bar, keep it.
+
+If the variants include multiple languages, you must provide `langInstructions` based on how the app actually switches language (look at the i18n setup in the code).
+If the variants include both light and dark themes, you must provide `themeInstructions` based on the actual theme toggle mechanism in the code.
+
+---
+
+## PresetConfig Schema
+
+The output must conform to this TypeScript schema. All fields are documented below.
+
+```typescript
+/** Top-level preset object for import */
+interface PresetImport {
+  name: string;        // Display name (e.g. "Homepage Hero", "Pricing Page")
+  description: string; // What this preset captures and why
+  config: PresetConfig;
+}
+
+/** The full preset configuration */
+type PresetConfig = {
+  /** The application URL (root URL of the project) */
+  url?: string;
+
+  /**
+   * Main capture prompt — natural language instructions for the agent.
+   * Ignored when `pages` is defined (each page has its own prompt).
+   */
+  prompt: string;
+
+  /** Device/viewport targets for capture */
+  targets: CaptureTarget[];
+
+  /** Output resolution multiplier. Default: 2 */
+  outputScale?: number;
+
+  /** Languages to capture. E.g. ["en", "fr", "de"] */
+  langs: string[];
+
+  /** Themes to capture */
+  themes: Array<"light" | "dark">;
+
+  /** Max agent iterations before giving up. Default: 60 */
+  maxIterations: number;
+
+  /**
+   * How to switch language in the UI.
+   * Must describe actual UI controls, not abstract instructions.
+   * Example: "Click the language dropdown in the footer and select the target language"
+   * If the app uses URL-based locale (e.g. /fr/pricing), say so.
+   */
+  langInstructions?: string;
+
+  /**
+   * How to switch theme in the UI.
+   * Must describe actual UI controls.
+   * Example: "Click the sun/moon icon in the top-right header to toggle dark mode"
+   */
+  themeInstructions?: string;
+
+  /** General navigation instructions applied to ALL captures (prepended to each page prompt) */
+  navigationInstructions?: string;
+
+  /**
+   * Login credentials. The agent handles login automatically before running page prompts.
+   * Only email/password auth is supported. OAuth, SSO, MFA, magic links are NOT supported.
+   */
+  credentials?: {
+    loginUrl?: string;  // Login page URL
+    email?: string;
+    password?: string;
+  };
+
+  /**
+   * Named capture pages — each page runs its own agent session with its own prompt.
+   * When defined, the top-level `prompt` field is ignored.
+   * CRITICAL: Each page runs independently with NO memory of other pages.
+   */
+  pages?: CapturePage[];
+
+  /**
+   * Isolated UI elements to extract from captured pages.
+   * Each element is cropped from the full page capture.
+   */
+  elements?: IsolatedElement[];
+
+  /**
+   * Network interception: replace API responses with LLM-generated mock data.
+   * Useful for showing populated UIs without real data.
+   */
+  mockData?: MockDataConfig;
+
+  /** Capture mode. Default: "screenshot" */
+  captureMode?: "screenshot" | "clip" | "video";
+
+  /** Clip definitions (when captureMode === "clip") */
+  clips?: ClipDefinition[];
+
+  /** Clip export options */
+  clipOptions?: ClipOptions;
+};
+
+interface CaptureTarget {
+  /** Unique identifier for this target */
+  id: string;
+  /** Display label */
+  label: string;
+  /** Browser viewport dimensions */
+  viewport: { width: number; height: number };
+  /**
+   * Optional device frame for mockup rendering.
+   * Available frames: "iphone-16-pro", "ipad-pro-11-m4", "ipad-air-m4",
+   *                   "macbook-air-13", "macbook-pro-16"
+   */
+  deviceFrame?: string;
+  /** Mockup rendering options */
+  mockupOptions?: MockupOptions;
+}
+
+interface MockupOptions {
+  orientation?: "portrait" | "landscape";
+  outputScale?: number;
+  showStatusBar?: boolean;
+  statusBar?: StatusBarConfig;
+  showDock?: boolean;        // Mac only
+  dockScale?: number;        // Mac only
+  dockMode?: "integrated" | "only-app"; // Mac only
+}
+
+interface StatusBarConfig {
+  time?: string;
+  signalStrength?: number;
+  wifiStrength?: number;
+  batteryLevel?: number;
+  batteryCharging?: boolean;
+  colorScheme?: "light" | "dark";
+  autoLocale?: boolean; // Auto-adapt status bar to capture language (default: true)
+}
+
+interface CapturePage {
+  /**
+   * Unique slug identifier. MUST match: /^[a-z0-9_-]+$/
+   * Use descriptive slugs: "pricing", "dashboard-overview", "settings-billing"
+   * AVOID generic slugs: "main", "page1", "page2", "screen1"
+   */
+  id: string;
+  /** Display name shown in the UI */
+  name: string;
+  /**
+   * Navigation prompt for the agent to reach this page/state.
+   * MUST be self-contained — the agent has NO memory of other pages.
+   * Include: where to navigate, what to click, what state to reach.
+   */
+  prompt: string;
+  /** Optional URL override if this page is at a different URL than the preset root */
+  url?: string;
+}
+
+interface IsolatedElement {
+  /** Element name (used in output filenames) */
+  name: string;
+  /**
+   * Description of the DOM element to crop.
+   * Must be visually identifiable — the agent matches against what it sees.
+   * GOOD: "The pricing table with 3 plan columns"
+   * GOOD: "The blue CTA button in the hero section"
+   * BAD: "The main content" (too vague)
+   */
+  description: string;
+  /** Source page id — when the preset has multiple pages, specify which page this element belongs to */
+  sourcePageId?: string;
+  /** Outscale config for padding around the element */
+  outscale?: OutscaleConfig;
+}
+
+interface OutscaleConfig {
+  /** Uniform padding on all 4 sides (pixels) */
+  padding?: number;
+  paddingTop?: number;
+  paddingRight?: number;
+  paddingBottom?: number;
+  paddingLeft?: number;
+  /** Percentage-based padding relative to element dimensions (0-100) */
+  paddingPercent?: number;
+  /** Background fill color. Default: transparent */
+  backgroundColor?: string;
+}
+
+interface MockDataConfig {
+  enabled: boolean;
+  /**
+   * Specific description of what data to generate.
+   * GOOD: "5 customer invoices with amounts between $50-500, mix of paid/pending/overdue statuses"
+   * BAD: "Some sample data"
+   */
+  description: string;
+  /** Explicitly target specific API endpoints to mock */
+  endpoints?: { url: string; method?: string }[];
+}
+
+interface ClipDefinition {
+  /** Unique slug identifier */
+  id: string;
+  /** Display name */
+  name: string;
+  /**
+   * What to record — the interaction the clip captures.
+   * When navigationScript is also provided, this describes ONLY the recording phase.
+   */
+  script: string;
+  /**
+   * Optional: navigation instructions to reach the page BEFORE recording starts.
+   * When provided, the navigation agent follows these to reach the page,
+   * then the recording system executes `script`.
+   */
+  navigationScript?: string;
+  /** Optional URL override */
+  url?: string;
+  /** Seconds to freeze the last frame before GIF loops. 0-10. Default: 0 */
+  holdLastFrameSec?: number;
+}
+
+interface ClipOptions {
+  /** Output format. Default: "gif" */
+  format?: "gif" | "mp4" | "both";
+  /** Max duration in seconds. Default: 8 */
+  maxDurationSec?: number;
+  /** GIF framerate. Default: 15 */
+  gifFps?: number;
+  /** GIF max width in pixels. Default: 800 */
+  gifMaxWidth?: number;
+  /** Show cursor animation. Default: true */
+  showCursor?: boolean;
+  /** Whether to loop GIF. Default: true */
+  loop?: boolean;
+}
+```
+
+---
+
+## Best Practices (Critical)
+
+### Prompt Writing
+The capture agent's success rate depends heavily on prompt quality. Write prompts with **strong navigation hints**:
+
+- **Add location references**: "in the left sidebar", "in the top-right header", "via the navigation bar"
+- **Use visual anchors**: "the blue button labeled 'Save'", "the table with column headers Name/Status/Date"
+- **Specify end-state**: what should be visible when the screenshot is taken
+- **Keep it concise**: 1-3 sentences. The agent handles micro-steps on its own
+
+**Bad prompt**: "Go to settings"
+**Good prompt**: "Navigate to the Settings page via the gear icon in the left sidebar. Show the 'General' tab with all form fields visible."
+
+### Named Pages
+- Each page runs as a **separate, independent agent session** with NO memory between pages
+- Page prompts must be **self-contained** — include all navigation steps from the root URL
+- If page B requires authentication, configure `credentials` in the preset — don't describe login steps in the prompt
+- Use **descriptive page IDs** as slugs: `pricing`, `dashboard-analytics`, `user-settings`
+- NEVER use generic IDs: `main`, `page1`, `page2`, `screen1`
+
+### Isolated Elements
+- Descriptions must reference **visually identifiable** DOM landmarks
+- Good: "The hero section containing the main heading and CTA button"
+- Bad: "The main content area"
+- Always specify `sourcePageId` when the preset has multiple pages
+
+### Theme & Language Instructions
+- Must describe **actual UI controls**, not abstract actions
+- Good: "Click the moon/sun toggle icon in the top-right corner of the header"
+- Bad: "Switch to dark mode"
+- If the app uses URL-based locales (e.g. `/fr/pricing`), mention it explicitly
+
+### Mock Data
+- Descriptions must be **specific enough for deterministic generation**
+- Include: number of items, value ranges, status distributions, data types
+- Good: "10 user accounts with realistic names, emails, roles (3 admin, 5 member, 2 viewer), last active dates within the past 30 days"
+- Bad: "Some users"
+
+### Credentials
+- Only email/password authentication is supported
+- OAuth, SSO, MFA, and magic links are NOT supported
+- When credentials are configured, the agent handles login automatically — do NOT repeat login steps in prompts
+- If a page requires auth but no credentials are configured, the capture will fail
+
+### What the Agent CANNOT Do
+- Upload files or handle file inputs
+- Handle OAuth, SSO, MFA, magic link auth
+- Type into non-auth, non-search fields (no form submissions that create data)
+- Delete or modify persistent data
+- Navigate outside the target domain
+- Remember state between separate page runs
+
+---
+
+## Common Targets
+
+Here are standard target configurations you can use:
+
+```json
+// Desktop (no device frame)
+{ "id": "desktop-1440x900", "label": "Desktop 1440x900", "viewport": { "width": 1440, "height": 900 } }
+
+// MacBook Air 13"
+{ "id": "macbook-air-13", "label": "MacBook Air 13\"", "viewport": { "width": 1440, "height": 900 }, "deviceFrame": "macbook-air-13", "mockupOptions": { "outputScale": 2 } }
+
+// iPhone 16 Pro (portrait)
+{ "id": "iphone-16-pro", "label": "iPhone 16 Pro", "viewport": { "width": 402, "height": 778 }, "deviceFrame": "iphone-16-pro", "mockupOptions": { "orientation": "portrait", "outputScale": 2 } }
+
+// iPad Pro 11" (landscape)
+{ "id": "ipad-pro-11", "label": "iPad Pro 11\" Landscape", "viewport": { "width": 1210, "height": 802 }, "deviceFrame": "ipad-pro-11-m4", "mockupOptions": { "orientation": "landscape", "outputScale": 2 } }
+```
+
+---
+
+## Output Format
+
+### Option 1: JSON Output (copy-paste)
+
+Output the preset as a JSON object. The user will paste this into AutoKap's import dialog.
+
+```json
+{
+  "name": "Preset Name",
+  "description": "What this preset captures",
+  "config": {
+    "prompt": "...",
+    "targets": [...],
+    "langs": ["en"],
+    "themes": ["light"],
+    "maxIterations": 60,
+    "outputScale": 2
+  }
+}
+```
+
+For multiple presets, output a JSON array:
+```json
+[
+  { "name": "...", "description": "...", "config": { ... } },
+  { "name": "...", "description": "...", "config": { ... } }
+]
+```
+
+### Option 2: Direct API Creation
+
+If an API key and project ID are provided in the prompt, create the preset directly via the AutoKap API:
+
+```bash
+curl -X POST "https://app.autokap.com/api/v1/presets" \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "project_id": "YOUR_PROJECT_ID",
+    "name": "Preset Name",
+    "description": "What this preset captures",
+    "config": { ... }
+  }'
+```
+
+When both an API key and project ID are available, prefer the API method for a seamless experience. Fall back to JSON output if the API call fails.
+
+---
+
+## Examples
+
+### Example 1: Simple Homepage Screenshot
+
+```json
+{
+  "name": "Homepage Hero",
+  "description": "Above-the-fold hero section of the landing page",
+  "config": {
+    "prompt": "Navigate to the homepage. Wait for the hero section to fully load including any animations and images. The page should show the main heading, subheading, and CTA button.",
+    "targets": [
+      { "id": "desktop-1440x900", "label": "Desktop 1440x900", "viewport": { "width": 1440, "height": 900 } }
+    ],
+    "langs": ["en"],
+    "themes": ["light"],
+    "maxIterations": 60,
+    "outputScale": 2
+  }
+}
+```
+
+### Example 2: Multi-Page Preset with Themes
+
+```json
+{
+  "name": "Marketing Pages",
+  "description": "Key marketing pages in light and dark mode",
+  "config": {
+    "targets": [
+      { "id": "desktop-1440x900", "label": "Desktop 1440x900", "viewport": { "width": 1440, "height": 900 } }
+    ],
+    "langs": ["en"],
+    "themes": ["light", "dark"],
+    "themeInstructions": "Click the sun/moon toggle icon in the top-right corner of the header navigation bar to switch between light and dark mode.",
+    "maxIterations": 60,
+    "outputScale": 2,
+    "prompt": "",
+    "pages": [
+      {
+        "id": "homepage",
+        "name": "Homepage",
+        "prompt": "Navigate to the homepage at /. Wait for the hero section to load completely with all images. The page should display the main value proposition heading and the 'Get Started' CTA button."
+      },
+      {
+        "id": "pricing",
+        "name": "Pricing Page",
+        "prompt": "Navigate to /pricing. Wait for the pricing cards to load. The page should show all plan tiers (Free, Pro, Enterprise) with their prices and feature lists visible. Select the 'Annual' billing toggle if available."
+      },
+      {
+        "id": "features",
+        "name": "Features Page",
+        "prompt": "Navigate to /features. Wait for the feature grid to fully render. The page should show the feature cards with icons and descriptions."
+      }
+    ]
+  }
+}
+```
+
+### Example 3: Clip (Animated GIF) Preset
+
+```json
+{
+  "name": "Dashboard Demo Clip",
+  "description": "Short animated GIF showing the dashboard interaction",
+  "config": {
+    "captureMode": "clip",
+    "targets": [
+      { "id": "desktop-1440x900", "label": "Desktop 1440x900", "viewport": { "width": 1440, "height": 900 } }
+    ],
+    "langs": ["en"],
+    "themes": ["light"],
+    "maxIterations": 60,
+    "outputScale": 2,
+    "prompt": "",
+    "clips": [
+      {
+        "id": "dashboard-filter",
+        "name": "Dashboard Filter Demo",
+        "navigationScript": "Navigate to /dashboard. Wait for the analytics charts to fully load and display data.",
+        "script": "Click the 'Date Range' dropdown in the top-right of the dashboard. Select 'Last 30 days'. Wait for the charts to update with the new data range.",
+        "holdLastFrameSec": 2
+      }
+    ],
+    "clipOptions": {
+      "format": "gif",
+      "maxDurationSec": 8,
+      "gifMaxWidth": 800,
+      "showCursor": true,
+      "loop": true
+    }
+  }
+}
+```
+
+---
+
+## Integration Endpoints API
+
+After creating presets and running captures, you can create **integration endpoints** — stable public URLs that serve your assets. Each endpoint maps to a specific capture (page, element, or clip) and supports dynamic variant selection via query parameters (`lang`, `theme`, `target`).
+
+### Create all endpoints for a preset
+
+```bash
+curl -X POST https://autokap.com/api/v1/endpoints \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{ "preset_id": "PRESET_ID" }'
+```
+
+This creates an endpoint for every page, isolated element, and clip defined in the preset. Existing endpoints are skipped (no duplicates).
+
+Response:
+```json
+{
+  "created": [{ "id": "abc123...", "label": "Homepage", "preset_id": "...", "asset_type": "screenshot" }],
+  "skipped": 0
+}
+```
+
+### Create endpoints for a composition
+
+```bash
+curl -X POST https://autokap.com/api/v1/endpoints \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{ "composition_id": "COMPOSITION_ID" }'
+```
+
+### List endpoints
+
+```bash
+# By preset
+curl "https://autokap.com/api/v1/endpoints?preset_id=PRESET_ID" \
+  -H "Authorization: Bearer $API_KEY"
+
+# By project
+curl "https://autokap.com/api/v1/endpoints?project_id=PROJECT_ID" \
+  -H "Authorization: Bearer $API_KEY"
+```
+
+### Update endpoint label
+
+```bash
+curl -X PATCH https://autokap.com/api/v1/endpoints/ENDPOINT_ID \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{ "label": "New Label" }'
+```
+
+### Delete an endpoint
+
+```bash
+curl -X DELETE https://autokap.com/api/v1/endpoints/ENDPOINT_ID \
+  -H "Authorization: Bearer $API_KEY"
+```
+
+### Export endpoints
+
+```bash
+# JSON export
+curl "https://autokap.com/api/v1/endpoints/export?preset_id=PRESET_ID" \
+  -H "Authorization: Bearer $API_KEY"
+
+# CSV export
+curl "https://autokap.com/api/v1/endpoints/export?preset_id=PRESET_ID&format=csv" \
+  -H "Authorization: Bearer $API_KEY"
+```
+
+### Serve an asset
+
+Assets are served publicly without authentication:
+
+```
+https://autokap.com/api/v1/assets/ENDPOINT_ID?lang=en&theme=dark&target=desktop
+```
+
+Query parameters: `lang`, `theme`, `target`, `w` (width), `quality`, `format` (png/webp).
+
+### Required API scopes
+
+- `endpoints:read` — list, get, and export endpoints
+- `endpoints:write` — create, update, and delete endpoints

package/dist/abort.d.ts

@@ -0,0 +1,5 @@
+export declare function createAbortError(message: string): Error;
+export declare function getAbortMessage(signal: AbortSignal | undefined, fallback: string): string;
+export declare function throwIfAborted(signal: AbortSignal | undefined, fallback?: string): void;
+export declare function isAbortError(error: unknown): boolean;
+export declare function sleepWithAbort(ms: number, signal?: AbortSignal): Promise<void>;

package/dist/abort.js

@@ -0,0 +1,44 @@
+export function createAbortError(message) {
+    const error = new Error(message);
+    error.name = 'AbortError';
+    return error;
+}
+export function getAbortMessage(signal, fallback) {
+    const reason = signal?.reason;
+    if (reason instanceof Error && reason.message)
+        return reason.message;
+    if (typeof reason === 'string' && reason.trim().length > 0)
+        return reason;
+    return fallback;
+}
+export function throwIfAborted(signal, fallback = 'Operation cancelled.') {
+    if (!signal?.aborted)
+        return;
+    throw createAbortError(getAbortMessage(signal, fallback));
+}
+export function isAbortError(error) {
+    return error instanceof Error && error.name === 'AbortError';
+}
+export async function sleepWithAbort(ms, signal) {
+    if (!signal) {
+        await new Promise((resolve) => setTimeout(resolve, ms));
+        return;
+    }
+    throwIfAborted(signal);
+    await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            cleanup();
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timeout);
+            cleanup();
+            reject(createAbortError(getAbortMessage(signal, 'Operation cancelled.')));
+        };
+        const cleanup = () => {
+            signal.removeEventListener('abort', onAbort);
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+//# sourceMappingURL=abort.js.map