autokap 1.6.2 → 1.6.3

package/assets/skill/references/STANDARDS.md

@@ -1,236 +0,0 @@
-# AutoKap Prompt Standards
-
-This document defines the contract every user-facing prompt produced by AutoKap must follow. It is the single source of truth referenced by `web/lib/prompts/blocks/*` and the prompt builders that compose them.
-
----
-
-## Why this charter exists
-
-AutoKap generates prompts that the user copy-pastes into their IDE so an AI assistant can:
-
-- inspect the user's codebase and add `data-ak` attributes
-- generate or edit a deterministic `ExecutionProgram`
-- scaffold a proxy, embed assets, or build a video demo
-
-The recipient assistant is rarely "AutoKap-aware":
-
-- it may be Cursor, Codex, GitHub Copilot, or Claude Code without the `autokap-preset` skill installed
-- it has no prior context about AutoKap's runtime model, opcode contract, or CLI
-
-When prompts are inconsistent, the assistant invents selectors, generates programs before inspecting the codebase, drops the CLI, and ignores the user's brief. We fix that by enforcing a **single, predictable structure across every prompt**.
-
-Two design principles flow from this:
-
-1. **Self-sufficient** — every prompt embeds a mini mental-model so the assistant can succeed even without the skill installed.
-2. **Predictable** — every prompt uses the same nine blocks in the same order. The assistant learns the shape once and applies it everywhere.
-
----
-
-## The nine blocks
-
-Every user-facing prompt is composed from the following blocks, in this order. Blocks are skipped only when explicitly marked optional.
-
-### 1. Header (required)
-
-3-5 lines. Names the product, the runtime model in one sentence, the task. Mentions the optional skill.
-
-```
-You are working on AutoKap, a screenshot-and-video automation tool. AutoKap presets
-are deterministic JSON programs (opcodes for Playwright) that the AutoKap CLI runs
-locally — there is no LLM at capture runtime. Your job here is to <one-line task>.
-If a skill named `autokap-preset` is installed in your environment, treat it as the
-source of truth — the rules below override anything that contradicts it.
-```
-
-The header replaces the implicit assumption that the assistant already knows AutoKap. It is the same in every prompt; only the `<one-line task>` changes.
-
-### 2. Before you write anything (required for any prompt that touches code)
-
-A numbered checklist of 3-5 actions the assistant must perform before generating the artifact. Always includes:
-
-- inspect the codebase
-- plan
-- ask the user when ambiguous
-- never invent UI details, selectors, or copy
-- search for existing `data-ak` before adding new ones (when applicable)
-
-```
-## Before you write anything
-
-1. Inspect the codebase: routes, auth, theme/locale system, components you may need to tag.
-2. Plan in your head (or in your planning tool if you have one) before generating.
-3. If anything is ambiguous (auth flow, target route, data shape), STOP and ask the user.
-   Do not invent UI details, selectors, or copy.
-4. Search for existing `data-ak` attributes first; only add new ones if none exist.
-5. If your environment supports parallel subagents, you may run codebase inspection
-   and program drafting in parallel — but do not skip step 3.
-```
-
-This block sits **immediately after the header**, before any technical detail. The assistant must read it before being tempted by the project context or the brief.
-
-### 3. User guidance (required and visible)
-
-The user's brief, isolated in its own section. The section name varies by task: `## User guidance`, `## What the user wants`, `## Preset brief`, `## What the demo should show`. The content is always the user's free-form input.
-
-When the user provided no guidance:
-
-```
-## User guidance
-
-_The user has not provided specific guidance for this task. Use sensible defaults
-based on the project context above._
-```
-
-When the user provided partial guidance (e.g. mock data guidance only), each piece appears in its own clearly-labelled subsection.
-
-This block sits **immediately after "Before you write anything"**, before any constraint. The assistant has just been told to inspect; the brief is the next thing it sees so it shapes inspection.
-
-### 4. Project context (required when applicable)
-
-Compact key/value list. Project name, project ID, base URL, credentials account ID, locale defaults. No prose.
-
-```
-## Project context
-
-- **Name**: Acme Dashboard
-- **ID**: `proj_abc123`
-- **Base URL**: `https://acme.example.com`
-- **Credentials account ID**: `cred_xyz789`
-```
-
-### 5. Hard constraints (required)
-
-Non-negotiable values: viewport variants, capture mode, mediaMode, baseUrl rules, etc. The "Variants (use these EXACTLY)" pattern is the canonical example. Use **bold** for emphasis on critical numbers and `code` for identifiers.
-
-### 6. Specific reminders (required when applicable)
-
-Auth, mock data, locale/theme handling, etc. — only the reminders that apply to the current mode. Anti-patterns are presented as `Don't / Do instead` tables, never bullets:
-
-```
-| Don't | Do instead |
-|---|---|
-| Use a CSS selector you guessed (`.btn-primary`) | Add a `data-ak="login-btn"` attribute and target `[data-ak="login-btn"]` |
-| Hardcode the auth cookie | Use `credentialsId` and let the runtime inject the right session |
-```
-
-### 7. How to persist (required for prompts that produce an artifact)
-
-CLI commands first. Useful flags listed (`--dry`, `--headed`, `--output`). Fallbacks (JSON file, dashboard import) explicitly labelled "fallback only".
-
-### 8. If you get stuck (required for any prompt that touches code)
-
-3 concrete scenarios minimum. Tells the assistant what to do at the failure points where it would otherwise improvise:
-
-```
-## If you get stuck
-
-- If you can't find a stable selector → ask the user before guessing.
-- If a CLI command fails → run with `--dry` first to validate, then re-run without `--dry`.
-- If the program runs but captures the wrong screen → report back with the AutoKap run log;
-  don't try to patch by adding more opcodes blindly.
-```
-
-### 9. Subagents hint (optional, multi-phase prompts only)
-
-A suggestion (never a requirement) for assistants that support parallel subagents. Always qualified with "if your environment supports..." so single-agent assistants are not derailed.
-
-```
-## If you have parallel subagents available
-
-This prompt has multiple phases (inspect → tag → generate → persist → integrate). If
-your environment supports subagents (Claude Code, multi-agent Cursor, etc.), consider
-parallelizing: agent 1 inspects the codebase and tags `data-ak`; agent 2 drafts the
-`ExecutionProgram` from the tagged components; you merge their outputs.
-```
-
----
-
-## Cross-cutting rules
-
-### Tone
-
-Direct imperative: `Do`, `Use`, `Never`, `Ask`. Never "you may want to consider", "perhaps", "if you wish". The assistant should know exactly what the prompt expects.
-
-### Markdown
-
-- `**bold**` for emphasis on critical values
-- `` `code` `` for identifiers, file paths, CLI flags
-- Tables for matrices and anti-patterns
-- Fenced code blocks (with language tag) for examples
-- `## Section` / `### Subsection` for hierarchy — the assistant should be able to refer to sections by name
-
-### No emojis
-
-Anywhere in any prompt. They look unprofessional and clutter terminal output when the prompt is shown verbatim.
-
-### Examples are concrete
-
-Every prompt that asks the assistant to produce an artifact contains at least one fully-formed example: a JSON snippet for opcodes, a bash one-liner for CLI commands, a JSX block for `data-ak` placement.
-
-### Anti-patterns are tables, not bullets
-
-```
-| Don't | Why / Do instead |
-|---|---|
-| ... | ... |
-```
-
-### Section names are stable
-
-The assistant should be able to refer to "the User guidance section" or "the Hard constraints section" and have it mean the same thing across all prompts.
-
----
-
-## Block composition pattern
-
-Each block exposes a `make*` function returning `string[]` (lines). Builders compose blocks by concatenating arrays and joining with `"\n"` at the end:
-
-```typescript
-import { joinBlocks } from "@/lib/prompts";
-import { makeHeader } from "@/lib/prompts/blocks/header";
-import { makeBeforeAnythingChecklist } from "@/lib/prompts/blocks/before-anything";
-import { makeUserGuidanceSection } from "@/lib/prompts/blocks/user-guidance";
-
-export function buildPresetPrompt(input: PresetPromptInput): string {
-  return joinBlocks([
-    makeHeader({ task: "generate an ExecutionProgram for this preset" }),
-    makeBeforeAnythingChecklist({ touchesCode: true, supportsSubagents: true }),
-    makeUserGuidanceSection({ brief: input.userBrief, label: "Preset brief" }),
-    // ... other blocks
-  ]);
-}
-```
-
-Blocks must:
-
-- accept typed parameters; never read environment variables or globals
-- be deterministic (same input → same output)
-- handle all "missing optional" cases internally (empty guidance, no credentials, etc.)
-- never add a trailing newline (the joiner handles spacing)
-
----
-
-## When the prompt does NOT touch code
-
-Some prompts do not produce code (e.g. an image-generation prompt for the Studio composition flow). For those:
-
-- Header is still required
-- Block 2 ("Before you write anything") is skipped
-- Block 8 ("If you get stuck") is skipped
-- Block 9 ("Subagents hint") is skipped
-- The remaining blocks apply if relevant
-
-These prompts are out of scope for the current refactor and follow a lighter contract.
-
----
-
-## Versioning and divergence
-
-This document is mirrored in `assets/skill/references/STANDARDS.md` so the installed skill has access to the same charter. When the charter changes:
-
-1. Update `web/lib/prompts/STANDARDS.md` first.
-2. Mirror the change to `assets/skill/references/STANDARDS.md`.
-3. Update the affected blocks in `web/lib/prompts/blocks/`.
-4. Re-run the snapshot tests on the builders to surface any drift.
-
-The blocks are the source of truth for what the prompts emit. This document is the source of truth for what the blocks should look like.

package/assets/skill/references/examples.md

@@ -1,88 +0,0 @@
-# Complete Examples Reference
-
-Use these examples as structural templates only. Adapt routes, selectors,
-variants, auth handling, and persistence to the user's actual codebase.
-
-## Example 1 — Anonymous screenshot preset
-
-Good for:
-
-- marketing homepage
-- pricing page
-- public docs landing page
-
-Pattern:
-
-1. `NAVIGATE`
-2. `DISMISS_OVERLAYS`
-3. optional `SET_LOCALE`
-4. optional `SET_THEME`
-5. `WAIT_FOR`
-6. `CAPTURE_SCREENSHOT`
-
-## Example 2 — Authenticated screenshot preset
-
-Good for:
-
-- dashboards
-- settings pages
-- project lists behind auth
-
-Pattern:
-
-1. hardcode the real login URL
-2. `NAVIGATE` to login
-3. `DISMISS_OVERLAYS`
-4. `WAIT_FOR` login fields
-5. `TYPE` `{{email}}`
-6. `TYPE` `{{password}}`
-7. `CLICK` submit
-8. `WAIT_FOR` the protected surface
-9. capture the full page or an `elementSelector`
-
-Never use `{{loginUrl}}`.
-
-## Example 3 — Clip preset
-
-Good for:
-
-- short product walkthroughs
-- showing a lightweight interaction
-- demo GIFs / MP4s
-
-Pattern:
-
-1. perform setup before recording
-2. `BEGIN_CLIP`
-3. run only the user-visible interaction sequence
-4. `END_CLIP`
-
-Prefer short, deterministic flows.
-
-## Example 4 — Mock data preset
-
-Good for:
-
-- empty dashboards
-- empty card grids
-- empty tables
-- charts that need seeded values for a compelling screenshot
-
-Pattern:
-
-1. add `data-ak` markers to the template and every variable child
-2. add hidden trigger/input receivers when the app can re-render the widget
-3. declare `mockDataInjection.groups`
-4. emit `INJECT_MOCK_DATA` before the screenshot
-
-## Final reminder
-
-These examples are reference shapes, not recipes to copy blindly.
-
-Before using one:
-
-- inspect the codebase
-- verify auth requirements
-- verify locale/theme handling
-- add authored selectors
-- persist the preset via API so the user can run `autokap run <preset-id>`

package/assets/skill/references/mock-data.md

@@ -1,178 +0,0 @@
-# Mock Data Injection Reference
-
-Use this reference when the user enables mock data generation or when a target
-capture would otherwise show empty tables, empty lists, empty charts, or other
-unhelpful placeholder states.
-
-## When to use it
-
-Use mock data when:
-
-- the page would otherwise render an empty state
-- the marketing value depends on populated cards, rows, charts, or metrics
-- the user explicitly enabled "Generate mock data"
-
-Do not use it just because the feature exists. If the real page already renders
-stable, attractive data, prefer the real state.
-
-## Core model
-
-Mock data injection has two complementary delivery mechanisms and the runtime
-applies both when they are wired:
-
-### Clone
-
-Clone a DOM template element, then write slot values into the cloned
-descendants.
-
-Best for:
-
-- tables
-- card grids
-- simple lists
-- badge rows
-
-### Trigger
-
-Write JSON into a hidden input and click a hidden button the app exposes. The
-component reads the payload and re-renders through normal app state.
-
-Best for:
-
-- charts
-- calendars
-- maps
-- library-owned DOM
-- anything likely to re-render and overwrite a clone
-
-## Default rule
-
-For modern React/Vue/Svelte apps, wire **both** clone and trigger whenever
-possible.
-
-Use only one mechanism when:
-
-- the page is pure server-rendered HTML with no client-side state: clone-only
-- the widget has no useful DOM template to clone: trigger-only
-
-## Critical slot rule
-
-Every variable UI element must be represented as a slot.
-
-Commonly missed slots:
-
-- dates
-- counts
-- status badges
-- labels that look static
-- type icons or icon variants
-- prices
-- ratings
-- role / owner / modified-at metadata
-- chart legends and series labels
-
-Rule of thumb:
-
-Walk through each JSX expression, ternary, and conditional class. If that value
-could differ across items, it should be a slot.
-
-## Step 1 — add authored markers
-
-Tag:
-
-- the clone template
-- the clone container
-- every variable child node
-- the hidden trigger input/button pair
-
-Example:
-
-```tsx
-<div data-ak="preset-card-grid">
-  {cards.map((card) => (
-    <article key={card.id} data-ak="preset-card">
-      <h3 data-ak="preset-card-title">{card.name}</h3>
-      <span data-ak="preset-card-type">{card.mediaMode}</span>
-      <span data-ak="preset-card-variant-count">{card.variantCount}</span>
-    </article>
-  ))}
-</div>
-
-<input type="hidden" data-ak-fill-input="preset-cards" />
-<button
-  type="button"
-  style={{ display: "none" }}
-  data-ak-fill-trigger="preset-cards"
-  onClick={(e) => {
-    const input = e.currentTarget.previousElementSibling as HTMLInputElement;
-    try {
-      const parsed = JSON.parse(input.value);
-      if (Array.isArray(parsed)) setCards(parsed);
-    } catch {
-      // ignore malformed payloads
-    }
-  }}
-/>
-```
-
-## Step 2 — declare `mockDataInjection.groups`
-
-Declare groups at the top level of the preset config, not inside `program`.
-
-Each group needs:
-
-- `name`
-- `description`
-- `slots[]`
-- `defaultValues[]`
-
-Keep values realistic for the user's domain. Seed 5-10 rows when that makes
-sense.
-
-## Step 3 — emit `INJECT_MOCK_DATA`
-
-Place each `INJECT_MOCK_DATA` opcode:
-
-- after the relevant `WAIT_FOR`
-- before the relevant `CAPTURE_SCREENSHOT`
-
-Wire both clone and trigger fields whenever possible:
-
-- `containerSelector`
-- `templateSelector`
-- `slotMappings[]`
-- `inputSelector`
-- `triggerSelector`
-
-Always keep the opcode non-blocking:
-
-```json
-{
-  "postcondition": { "type": "always" },
-  "recovery": {
-    "retries": 0,
-    "useSelectorMemory": false,
-    "useAltInteraction": false,
-    "allowReload": false,
-    "allowHealer": false
-  }
-}
-```
-
-## Implementation rules
-
-- `slotMappings[].selector` is relative to the cloned template item
-- `removeTemplate: true` when the original template should disappear
-- `replaceExisting: true` on the group when placeholder content should be wiped
-- use `attribute` only when the value belongs in an attribute such as `src`
-- a group counts as applied if at least one delivery mechanism succeeds
-
-## When not to use `INJECT_MOCK_DATA`
-
-Use lower-level DOM mutation opcodes instead when the change is narrow:
-
-- `CLONE_ELEMENT`
-- `REMOVE_ELEMENT`
-- `SET_ATTRIBUTE`
-
-Reserve `INJECT_MOCK_DATA` for real structured seed-data scenarios.

package/dist/auth-capture.d.ts

@@ -1,17 +0,0 @@
-export interface AuthCaptureOptions {
-    apiBaseUrl: string;
-    apiKey: string;
-    projectId: string;
-    accountId: string;
-    startUrl: string;
-}
-/**
- * Opens a headed Chromium window, lets the user log in, and uploads the
- * resulting storageState (cookies + localStorage, HttpOnly included) to the
- * given project credentials account.
- *
- * The session is captured continuously via polling so we don't depend on the
- * user explicitly clicking a button — closing the window after login is
- * enough. A "Save & close" button is also rendered for explicit confirmation.
- */
-export declare function captureAuthSession(options: AuthCaptureOptions): Promise<void>;