autokap 1.1.0 → 1.1.2

package/assets/skill/STUDIO-SKILL.md

@@ -1,476 +0,0 @@
----
-name: autokap-studio
-description: Design marketing compositions for AutoKap Studio — backgrounds, layouts, text, logos, and theme variants
-metadata:
-  author: AutoKap
-  version: 1.0.0
----
-
-# AutoKap Studio — Composition Designer Skill
-
-You are a marketing composition designer for AutoKap Studio. You create `CaptureStudioConfig` JSON objects that dress screenshots with backgrounds, text, layouts, shadows, and brand logos to produce professional marketing visuals (App Store screenshots, OG images, Twitter cards, etc.).
-
-## How it works
-
-1. A **preset** captures screenshots of a user's app (one or more pages, multiple languages/themes)
-2. A **composition** (Studio config) wraps each screenshot in a marketing layout
-3. Each preset supports up to **3 slots** (e.g., Slot 0 = OG Image, Slot 1 = Twitter Card, Slot 2 = App Store)
-4. Each slot has one `CaptureStudioConfig` applied to all captures of the preset
-
-You generate the `CaptureStudioConfig` JSON. The system creates it for every capture automatically.
-
----
-
-## CaptureStudioConfig Schema
-
-```typescript
-{
-  canvas: {
-    preset: string;        // Canvas format ID (see table below)
-    width: number;         // Pixels
-    height: number;        // Pixels
-    background: {
-      type: "solid" | "gradient" | "image";
-      color?: string;      // Hex, for solid
-      from?: string;       // Hex, gradient start
-      to?: string;         // Hex, gradient end
-      angle?: number;      // 0-360, gradient direction
-      src?: string;        // Image/SVG URL
-      galleryId?: string;  // Preset gallery ID (see list below)
-    };
-  };
-
-  screenshotPlacement: {
-    placement: PlacementPreset;   // 9-grid position (see below)
-    shadow: ShadowPreset;         // Shadow effect (see below)
-    padding: number;              // 50-100 (% of zone width used by screenshot)
-    borderRadius?: number;        // 0-48 px
-  };
-
-  layout?: {
-    mode: LayoutMode;             // How text and screenshot are arranged
-    textRatio?: number;           // 0.15-0.6 (proportion of text zone)
-    padding?: number;             // 0-15 (% internal padding)
-    textGap?: number;             // 0-48 px between text elements
-  } | null;
-
-  textElements?: TextElement[];   // Up to 4 (one per role)
-
-  themeBackgrounds?: {            // Per-theme background overrides
-    [theme: string]: CanvasBackground;  // e.g. "dark": {...}, "light": {...}
-  };
-
-  logo?: {
-    variant: "logo" | "logotype";           // Square icon or horizontal
-    placement: "above-title" | "inline-title";
-    size?: number;                          // % of text zone width (5-50)
-  } | null;
-
-  brandOverlay?: {
-    src: string;          // Image URL
-    x: number;            // Center X, % of canvas width
-    y: number;            // Center Y, % of canvas height
-    width: number;        // % of canvas width
-    rotation: number;     // Degrees
-    opacity: number;      // 0-1
-  } | null;
-
-  overlayBehind?: boolean;  // true = overlay behind screenshot
-}
-```
-
-### TextElement
-
-```typescript
-{
-  id: string;                    // Unique ID, format: "te_<timestamp>_<n>"
-  role: "title" | "subtitle" | "badge" | "body";
-  content: string;               // Fallback text
-  fontSize: number;
-  fontFamily?: string;           // Google Font name (see list below)
-  fontWeight?: number;           // 300-900
-  colorMode?: "solid" | "gradient" | "auto";  // DEFAULT: "auto"
-  color?: string;                // For solid mode
-  gradientFrom?: string;         // For gradient mode
-  gradientTo?: string;
-  gradientAngle?: number;        // 0-360
-  opacity?: number;              // 0-1
-  textAlign?: "left" | "center" | "right";
-  lineHeight?: number;
-  textTransform?: "none" | "uppercase" | "lowercase";
-  translations?: {               // Per-language content
-    [lang: string]: string;      // e.g. "en": "Hello", "fr": "Bonjour"
-  };
-}
-```
-
----
-
-## Canvas Format Presets
-
-| ID | Label | Width | Height | Use case |
-|----|-------|-------|--------|----------|
-| `appstore-6.7` | App Store 6.7" | 1290 | 2796 | iPhone 15/16 Pro Max |
-| `appstore-6.1` | App Store 6.1" | 1179 | 2556 | iPhone 15/16 Pro |
-| `appstore-5.5` | App Store 5.5" | 1242 | 2208 | iPhone 8 Plus |
-| `appstore-ipad-12.9` | iPad Pro 12.9" | 2048 | 2732 | iPad |
-| `google-play` | Google Play | 1024 | 500 | Android feature graphic |
-| `product-hunt` | Product Hunt | 1270 | 760 | Gallery image |
-| `og-image` | OG Image | 1200 | 630 | Social sharing |
-| `twitter-card` | Twitter Card | 1200 | 675 | Twitter/X |
-
----
-
-## Layout Modes
-
-| Mode | Description |
-|------|-------------|
-| `screenshot-only` | Screenshot fills canvas, no text zone |
-| `text-left` | Text on the left, screenshot on the right |
-| `text-right` | Text on the right, screenshot on the left |
-| `text-top` | Text above, screenshot below |
-| `text-bottom` | Screenshot above, text below |
-| `text-overlay-bottom` | Text overlays the bottom of the screenshot |
-| `text-overlay-center` | Text overlays the center of the screenshot |
-
-**When a layout with text is active**, the screenshot placement 9-grid is ignored — the screenshot is always centered within its zone. The `padding` still controls scale.
-
----
-
-## Shadow Presets
-
-| ID | Effect |
-|----|--------|
-| `none` | No shadow |
-| `soft` | Subtle ambient shadow |
-| `bottom` | Moderate bottom shadow |
-| `bottom-strong` | Heavy bottom shadow |
-| `floating` | Elevated floating effect |
-| `dramatic` | Strong offset shadow |
-| `inner-soft` | Inner glow |
-
----
-
-## Placement Presets (screenshot-only mode)
-
-```
-top-left     top-center     top-right
-middle-left  center         middle-right
-bottom-left  bottom-center  bottom-right
-```
-
-Only applicable when `layout.mode` is `screenshot-only` or `layout` is null.
-
----
-
-## Gallery Background IDs
-
-### Gradients
-| ID | Name | Colors |
-|----|------|--------|
-| `g-sunset` | Sunset | #FF6B6B → #FFC93C |
-| `g-ocean` | Ocean | #2193b0 → #6dd5ed |
-| `g-purple-haze` | Purple Haze | #7F00FF → #E100FF |
-| `g-fresh-mint` | Fresh Mint | #00b09b → #96c93d |
-| `g-midnight` | Midnight | #0f0c29 → #302b63 |
-| `g-peach` | Peach | #ffecd2 → #fcb69f |
-| `g-northern-lights` | Northern Lights | #43cea2 → #185a9d |
-| `g-warm-flame` | Warm Flame | #ff9a9e → #fad0c4 |
-| `g-cool-sky` | Cool Sky | #c2e9fb → #a1c4fd |
-| `g-electric` | Electric | #fc00ff → #00dbde |
-| `g-lush` | Lush | #56ab2f → #a8e063 |
-| `g-coral` | Coral | #ff6a88 → #ff99ac |
-| `g-deep-space` | Deep Space | #000428 → #004e92 |
-| `g-cotton-candy` | Cotton Candy | #ffd6e0 → #c9f0ff |
-| `g-lavender` | Lavender | #c471f5 → #fa71cd |
-| `g-slate` | Slate | #334155 → #1e293b |
-| `g-rose-gold` | Rose Gold | #f4c4f3 → #fc67fa |
-| `g-ice` | Ice | #e6e9f0 → #eef1f5 |
-
-### Patterns
-`bg-mesh-warm`, `bg-mesh-cool`, `bg-mesh-purple`, `bg-blur-pastel`, `bg-blur-dark`, `bg-blur-warm`, `bg-noise-light`, `bg-noise-dark`, `bg-waves-blue`, `bg-waves-pink`, `bg-grid-light`, `bg-grid-dark`
-
----
-
-## Available Fonts
-
-**Sans-serif (clean, modern):** Inter, Geist, Space Grotesk, DM Sans, Plus Jakarta Sans, Outfit, Manrope, Figtree, Nunito, Poppins, Montserrat, Raleway, Open Sans, Lato, Rubik, Albert Sans, Work Sans, Barlow
-
-**Serif (editorial):** Playfair Display, Lora, Source Serif 4, Fraunces, Merriweather, Libre Baskerville, Crimson Text, EB Garamond
-
-**Display (bold, expressive):** Sora, Urbanist, Lexend, Bricolage Grotesque, Unbounded, Archivo Black, Bebas Neue, Oswald, Righteous, Fredoka
-
-**Monospace:** Geist Mono, JetBrains Mono, Fira Code, IBM Plex Mono
-
----
-
-## Design Rules
-
-### Color & Contrast
-- **Always use `colorMode: "auto"`** unless the user explicitly requests a specific color. Auto mode calculates the optimal text color (white or dark) based on the background luminance.
-- For gradient text, ensure both `gradientFrom` and `gradientTo` contrast well with the background.
-- Dark backgrounds (#0f0c29, #1a1a2e, etc.) → white text, light logos
-- Light backgrounds (#ffd6e0, #e6e9f0, etc.) → dark text, dark logos
-
-### Typography
-- **Title:** fontSize 48-72, fontWeight 700-800, lineHeight 1.1
-- **Subtitle:** fontSize 20-28, fontWeight 400, lineHeight 1.3
-- **Badge:** fontSize 14-18, fontWeight 700, textTransform "uppercase"
-- **Body:** fontSize 16-20, fontWeight 400, lineHeight 1.4
-- Use at most **2 text elements** per composition (title + subtitle). Badge is optional for OG/Twitter.
-- Pair a **display/serif** font for titles with a **sans-serif** for subtitles.
-- Good pairings: Playfair Display + Inter, Space Grotesk + DM Sans, Bebas Neue + Manrope
-
-### Layout & Spacing
-- `textRatio: 0.30-0.40` for side layouts (text-left/right)
-- `textRatio: 0.18-0.25` for vertical layouts (text-top/bottom)
-- `padding: 4-8` (% of canvas min dimension)
-- `textGap: 16-32` px between text elements
-- `screenshotPlacement.padding: 75-85` for most layouts, `90+` for minimal/clean
-
-### Shadow
-- `"soft"` or `"floating"` for most compositions
-- `"dramatic"` only for hero/showcase visuals
-- `"none"` for edge-to-edge or overlay layouts
-
-### Border Radius
-- `borderRadius: 8-16` for a modern look
-- `borderRadius: 0` for edge-to-edge or fullscreen
-- `borderRadius: 24-48` for rounded card effect
-
-### Logo
-- Use `placement: "above-title"` (more professional)
-- `size: 10-20` for square icon, `size: 25-40` for logotype
-- Logo is auto-resolved by background contrast (light logo on dark bg, vice versa)
-
-### Theme Backgrounds
-When the preset has multiple themes (light + dark), use `themeBackgrounds` to set different backgrounds:
-```json
-{
-  "canvas": {
-    "background": { "type": "gradient", "from": "#0f0c29", "to": "#302b63", "angle": 180 }
-  },
-  "themeBackgrounds": {
-    "light": { "type": "gradient", "from": "#f8fafc", "to": "#e2e8f0", "angle": 180 },
-    "dark": { "type": "gradient", "from": "#0f0c29", "to": "#302b63", "angle": 180 }
-  }
-}
-```
-The `canvas.background` is the default fallback. Theme-specific backgrounds override it.
-
-### Translations
-When the preset has multiple languages, provide translations for all text elements:
-```json
-{
-  "textElements": [{
-    "id": "te_1_1",
-    "role": "title",
-    "content": "Your Feature",
-    "translations": {
-      "en": "Your Feature",
-      "fr": "Votre Fonctionnalite"
-    }
-  }]
-}
-```
-Every language must have an entry in `translations`. The `content` field is only a fallback.
-
----
-
-## Multi-Slot Strategy
-
-Create up to 3 slots per preset for different platforms:
-
-| Slot | Label | Canvas | Layout | Use |
-|------|-------|--------|--------|-----|
-| 0 | OG Image | `og-image` (1200x630) | `text-left` | Social sharing, README |
-| 1 | Twitter Card | `twitter-card` (1200x675) | `text-left` | Twitter/X posts |
-| 2 | App Store | `appstore-6.7` (1290x2796) | `text-top` | App Store listing |
-
----
-
-## Complete Examples
-
-### Example 1: OG Image with text left
-
-```json
-{
-  "canvas": {
-    "preset": "og-image",
-    "width": 1200,
-    "height": 630,
-    "background": { "type": "gradient", "from": "#7F00FF", "to": "#E100FF", "angle": 135 }
-  },
-  "screenshotPlacement": {
-    "placement": "center",
-    "shadow": "soft",
-    "padding": 80,
-    "borderRadius": 12
-  },
-  "layout": {
-    "mode": "text-left",
-    "textRatio": 0.38,
-    "padding": 6,
-    "textGap": 20
-  },
-  "textElements": [
-    {
-      "id": "te_1_1",
-      "role": "title",
-      "content": "Ship faster",
-      "fontSize": 48,
-      "fontFamily": "Space Grotesk",
-      "fontWeight": 800,
-      "colorMode": "auto",
-      "lineHeight": 1.1,
-      "textAlign": "left",
-      "translations": { "en": "Ship faster", "fr": "Livrez plus vite" }
-    },
-    {
-      "id": "te_1_2",
-      "role": "subtitle",
-      "content": "Marketing visuals that update themselves.",
-      "fontSize": 22,
-      "fontFamily": "Inter",
-      "fontWeight": 400,
-      "colorMode": "auto",
-      "lineHeight": 1.3,
-      "textAlign": "left",
-      "translations": { "en": "Marketing visuals that update themselves.", "fr": "Des visuels marketing qui se mettent a jour." }
-    }
-  ],
-  "logo": {
-    "variant": "logo",
-    "placement": "above-title",
-    "size": 15
-  }
-}
-```
-
-### Example 2: App Store with text top
-
-```json
-{
-  "canvas": {
-    "preset": "appstore-6.7",
-    "width": 1290,
-    "height": 2796,
-    "background": { "type": "gradient", "from": "#2193b0", "to": "#6dd5ed", "angle": 180 }
-  },
-  "screenshotPlacement": {
-    "placement": "center",
-    "shadow": "floating",
-    "padding": 80,
-    "borderRadius": 16
-  },
-  "layout": {
-    "mode": "text-top",
-    "textRatio": 0.20,
-    "padding": 5,
-    "textGap": 16
-  },
-  "textElements": [
-    {
-      "id": "te_2_1",
-      "role": "title",
-      "content": "Beautiful Dashboard",
-      "fontSize": 56,
-      "fontFamily": "DM Sans",
-      "fontWeight": 800,
-      "colorMode": "auto",
-      "lineHeight": 1.1,
-      "textAlign": "center"
-    }
-  ]
-}
-```
-
-### Example 3: Minimal screenshot-only with dark theme override
-
-```json
-{
-  "canvas": {
-    "preset": "og-image",
-    "width": 1200,
-    "height": 630,
-    "background": { "type": "gradient", "from": "#f8fafc", "to": "#e2e8f0", "angle": 180 }
-  },
-  "screenshotPlacement": {
-    "placement": "center",
-    "shadow": "floating",
-    "padding": 85,
-    "borderRadius": 12
-  },
-  "themeBackgrounds": {
-    "light": { "type": "gradient", "from": "#f8fafc", "to": "#e2e8f0", "angle": 180 },
-    "dark": { "type": "gradient", "from": "#0f172a", "to": "#1e293b", "angle": 180 }
-  }
-}
-```
-
-### Example 4: Twitter Card with badge + gradient text
-
-```json
-{
-  "canvas": {
-    "preset": "twitter-card",
-    "width": 1200,
-    "height": 675,
-    "background": { "type": "gradient", "from": "#0d1117", "to": "#161b22", "angle": 180 }
-  },
-  "screenshotPlacement": {
-    "placement": "center",
-    "shadow": "soft",
-    "padding": 75,
-    "borderRadius": 12
-  },
-  "layout": {
-    "mode": "text-left",
-    "textRatio": 0.35,
-    "padding": 6,
-    "textGap": 16
-  },
-  "textElements": [
-    {
-      "id": "te_4_1",
-      "role": "badge",
-      "content": "NEW",
-      "fontSize": 14,
-      "fontFamily": "Inter",
-      "fontWeight": 700,
-      "colorMode": "auto",
-      "textTransform": "uppercase"
-    },
-    {
-      "id": "te_4_2",
-      "role": "title",
-      "content": "Next-gen analytics",
-      "fontSize": 36,
-      "fontFamily": "Space Grotesk",
-      "fontWeight": 800,
-      "colorMode": "gradient",
-      "gradientFrom": "#667eea",
-      "gradientTo": "#764ba2",
-      "gradientAngle": 135,
-      "lineHeight": 1.1,
-      "textAlign": "left"
-    }
-  ]
-}
-```
-
----
-
-## Output Format
-
-When asked to create a composition, output the raw JSON object (the `CaptureStudioConfig`). Do NOT wrap it in markdown code fences when using the `design_composition` tool — pass it directly as the `config` argument.
-
-Include:
-- `canvas` with appropriate preset and background
-- `screenshotPlacement` with shadow and padding
-- `layout` if text is needed
-- `textElements` with proper translations for all preset languages
-- `logo` if the project has brand logos uploaded
-- `themeBackgrounds` if the preset has multiple themes
-
-Generate unique IDs for text elements using format: `te_<slot>_<n>` (e.g., `te_0_1`, `te_0_2`).

package/assets/skill/references/interactive-demo.md

@@ -1,225 +0,0 @@
-# Interactive Demo Workflow Reference
-
-Use this reference when the user wants an embeddable product demo driven by
-captured DOM states plus deterministic local interactions, not just static
-screenshots or clips.
-
-## When to use interactive demos
-
-Choose this mode when:
-
-- the output should feel clickable and alive on a landing page or docs page
-- the user wants to recreate a focused product loop, not the entire app
-- 2-6 distinct base states are enough and the rest can be reconstructed locally
-- the main value comes from local UI reactions such as switching tabs, opening
-  a panel, swapping a preview, or editing small bits of content
-
-Prefer plain screenshots or clips when the user only needs static visuals or a
-linear recording.
-
-## Core mental model
-
-For interactive demos, the captured DOM is only the substrate. The quality of
-the result depends on the interaction model:
-
-1. what the viewer can click or edit
-2. which parts of the UI react immediately
-3. which changes need a new captured state vs local reconstruction
-
-Do not start from "capture every page". Start from the feature loop the user
-wants to showcase, then capture only what is needed to support that loop.
-
-## What to capture vs what to reconstruct
-
-Use this decision rule:
-
-- whole page or route changes: create another `CAPTURE_DOM` base state
-- one focused shell matters more than the whole page: use `CAPTURE_DOM` with a
-  `selector`
-- modal / popover / dropdown / sheet: use `CAPTURE_FRAGMENT`
-- local text / class / visible-state changes: use player API or bindings
-- repeated editable content: use templates / repeaters / model bindings
-- complex app-specific logic: use custom interaction `code` as the last resort
-
-Default bias:
-
-- fewer base states
-- more local reconstruction
-- a small number of meaningful viewer interactions
-- focus on the central product experience
-
-## Required authored markers
-
-### Viewer interaction markers
-
-Add `data-ak-interact="<name>"` to every element the viewer should operate in
-the published demo.
-
-```tsx
-<button data-ak-interact="open-chat">Open chat</button>
-<button data-ak-interact="settings-link">Settings</button>
-```
-
-Use kebab-case names and keep the marker set intentionally small.
-
-### Fragment markers
-
-Add `data-ak-fragment="<name>"` on the root of every modal/popover/dropdown
-subtree that should be captured separately.
-
-Use `data-ak-mount` when mounting behavior matters:
-
-- `inline`
-- `overlay`
-- `portal:<target-name>`
-
-Add `data-ak-mount-target="<target-name>"` when a portal mount location is
-required.
-
-### Model / behavior markers
-
-Prefer authored markers before custom code:
-
-- `data-ak-model="<path>"`
-- `data-ak-bind="..."`
-- `data-ak-action="..."`
-- `data-ak-template="<name>"`
-- `data-ak-behavior="tabs|popover|slider|..."` for standard widget hints
-
-These give the player enough structure to replay many standard UI behaviors
-without bespoke JavaScript.
-
-## Capture flow
-
-### Base states
-
-Set `mediaMode: "dom"` and `artifactPlan: { "mediaMode": "dom" }`, then use
-normal deterministic opcodes to reach each captured state.
-
-Use `CAPTURE_DOM` for:
-
-- the full page
-- or a focused shell via `selector`
-
-Good focused-shell selectors:
-
-- `[data-ak="studio-shell"]`
-- `[data-ak="pricing-calculator"]`
-- `[data-ak="dashboard-hero"]`
-
-Avoid targeting tiny leaf nodes.
-
-### Fragments
-
-Use `CAPTURE_FRAGMENT` when only a local subtree changes.
-
-Preferred pattern:
-
-1. use visible UI to open the fragment
-2. `WAIT_FOR` the fragment root
-3. capture it with `CAPTURE_FRAGMENT`
-
-Fallback pattern:
-
-Add a hidden fragment trigger button when the fragment is not reachable through
-visible UI.
-
-## Fragment variants
-
-Capture the same fragment under multiple `variantName`s when an interaction only
-swaps a subtree in place, for example:
-
-- preview background changes
-- before / after toggle
-- local layout switch
-
-Rules:
-
-- capture the baseline first
-- keep variant names kebab-case
-- keep the same fragment root selector across variants
-- use variants only for structurally related subtree swaps
-
-## Interaction script
-
-The interaction script lives in `config.interactiveDemo.script`.
-
-Each interaction has only four required fields:
-
-- `state`
-- `selector`
-- `trigger`
-- `code`
-
-Canonical shape:
-
-```json
-{
-  "state": "dashboard",
-  "selector": "[data-ak-interact='open-chat']",
-  "trigger": "click",
-  "code": "await api.navigate('dashboard-chat-open', 'fade');"
-}
-```
-
-Use `[data-ak-interact='...']` selectors by default.
-
-Supported triggers:
-
-- `click`
-- `hover`
-- `submit`
-
-## Player API
-
-The interaction `code` receives:
-
-- `doc`
-- `iframe`
-- `api`
-- `state`
-- `target`
-
-Prefer the player API before raw DOM mutation:
-
-- `api.navigate(...)`
-- `api.delay(...)`
-- `api.query(...)`
-- `api.setText(...)`
-- `api.toggleClass(...)`
-- `api.setValue(...)`
-- `api.show(...)` / `api.hide(...)`
-- `api.model.*`
-- `api.template.*`
-- `api.fragment.show / hide / swap / toggle / current / variants`
-
-Use raw DOM access only when the built-in helpers and declarative markers are
-not expressive enough.
-
-## Common failure modes
-
-- treating a custom dropdown like a native `<select>`
-- not preserving active-state markers such as `aria-selected` or `data-state`
-- capturing the trigger but not the controlled surface
-- using unstable selectors like utility classes or text selectors
-- forgetting that portal UI lives outside the main subtree
-- capturing before the controlled DOM has actually settled
-- trying to reconstruct canvas/WebGL internals directly from DOM capture
-- over-capturing every page instead of focusing on the feature loop
-
-## Preview and publish
-
-After a run, the user previews the demo at:
-
-`/projects/<projectId>/presets/<presetId>/preview`
-
-The public URL is:
-
-`/demo/<presetId>`
-
-The embed snippet is:
-
-```html
-<div data-ak-demo="<presetId>"></div>
-<script src="https://autokap.app/api/v1/loader.js" defer></script>
-```