screenhand 0.4.1 → 0.4.3

package/dist-playbooks/calendar-create-event.json

@@ -0,0 +1,20 @@
+{
+  "id": "calendar-create-event",
+  "name": "create-event",
+  "description": "create-event",
+  "platform": "calendar",
+  "version": "1.0.0",
+  "tags": [
+    "calendar",
+    "recorded"
+  ],
+  "successCount": 0,
+  "failCount": 0,
+  "steps": [
+    {
+      "action": "applescript",
+      "script": "tell application \"Calendar\"\n\tset evStart to current date\n\tset evEnd to current date\n\tset hours of evEnd to (hours of evEnd) + 1\n\tmake new event at end of events of calendar \"Home\" with properties {summary:\"New Event\", start date:evStart, end date:evEnd}\n\treturn \"created\"\nend tell",
+      "description": "AppleScript: tell application \"Calendar\"\n\tset evStart to current date\n\tset evEnd to current d..."
+    }
+  ]
+}

package/dist-playbooks/calendar-list-events.json

@@ -0,0 +1,20 @@
+{
+  "id": "calendar-list-events",
+  "name": "list-upcoming-events",
+  "description": "list-upcoming-events",
+  "platform": "calendar",
+  "version": "1.0.0",
+  "tags": [
+    "calendar",
+    "recorded"
+  ],
+  "successCount": 0,
+  "failCount": 0,
+  "steps": [
+    {
+      "action": "applescript",
+      "script": "tell application \"Calendar\"\n\tset startDate to current date\n\tset endDate to startDate + (7 * days)\n\tset output to \"\"\n\trepeat with c in every calendar\n\t\tset upcoming to (every event of c whose start date >= startDate and start date <= endDate)\n\t\trepeat with e in upcoming\n\t\t\tset output to output & name of c & \": \" & summary of e & \" -- \" & start date of e & linefeed\n\t\tend repeat\n\tend repeat\n\tif output is \"\" then return \"No events this week\"\n\treturn output\nend tell",
+      "description": "AppleScript: tell application \"Calendar\"\n\tset startDate to current date\n\tset endDate to start..."
+    }
+  ]
+}

package/dist-playbooks/calendar-navigate-views.json

@@ -0,0 +1,47 @@
+{
+  "id": "calendar-navigate-views",
+  "name": "navigate-views",
+  "description": "navigate-views",
+  "platform": "calendar",
+  "version": "1.0.0",
+  "tags": [
+    "calendar",
+    "recorded"
+  ],
+  "successCount": 0,
+  "failCount": 0,
+  "steps": [
+    {
+      "action": "key",
+      "keys": [
+        "cmd",
+        "2"
+      ],
+      "description": "Key: cmd+2"
+    },
+    {
+      "action": "key",
+      "keys": [
+        "cmd",
+        "3"
+      ],
+      "description": "Key: cmd+3"
+    },
+    {
+      "action": "key",
+      "keys": [
+        "cmd",
+        "1"
+      ],
+      "description": "Key: cmd+1"
+    },
+    {
+      "action": "key",
+      "keys": [
+        "cmd",
+        "t"
+      ],
+      "description": "Key: cmd+t"
+    }
+  ]
+}

package/dist-playbooks/calendar-open-settings.json

@@ -0,0 +1,20 @@
+{
+  "id": "calendar-open-settings",
+  "name": "open-settings",
+  "description": "open-settings",
+  "platform": "calendar",
+  "version": "1.0.0",
+  "tags": [
+    "calendar",
+    "recorded"
+  ],
+  "successCount": 0,
+  "failCount": 0,
+  "steps": [
+    {
+      "action": "applescript",
+      "script": "tell application \"System Events\"\n\ttell process \"Calendar\"\n\t\tclick menu item \"Settings\u2026\" of menu \"Calendar\" of menu bar 1\n\tend tell\nend tell",
+      "description": "AppleScript: tell application \"System Events\"\n\ttell process \"Calendar\"\n\t\tclick menu item \"Set..."
+    }
+  ]
+}

package/dist-playbooks/google-ads-transparency-competitor-research.json

@@ -0,0 +1,89 @@
+{
+  "id": "google-ads-transparency-competitor-research",
+  "name": "Google Ads Transparency — Competitor Research",
+  "description": "Open the Google Ads Transparency Center for a domain in India and extract active ad counts, advertiser labels, and creative links.",
+  "platform": "google-ads-transparency",
+  "version": "1.0.0",
+  "urlPatterns": [
+    "*adstransparency.google.com*"
+  ],
+  "tags": [
+    "google",
+    "ads-transparency",
+    "competitor-research",
+    "browser",
+    "cdp"
+  ],
+  "successCount": 0,
+  "failCount": 0,
+  "urls": {
+    "domain_lookup": "https://adstransparency.google.com/?region=IN&domain={DOMAIN}"
+  },
+  "selectors": {
+    "results": {
+      "search_input": "input.input.input-area",
+      "creative_cards": "a[href*='/advertiser/'][href*='/creative/']",
+      "see_all_ads_button": "material-button.grid-expansion-button"
+    }
+  },
+  "flows": {
+    "domain_lookup": {
+      "steps": [
+        "Open the domain URL directly",
+        "Expand See all ads if available",
+        "Extract ad count, advertiser labels, and creative links"
+      ],
+      "guards": [
+        "Use DOMAIN as the landing-page domain, not the brand name"
+      ],
+      "why": "Direct domain URLs are more stable than homepage search interaction."
+    }
+  },
+  "detection": {
+    "on_ads_transparency": "location.hostname.includes('adstransparency.google.com')"
+  },
+  "errors": [
+    {
+      "error": "the page confirms inventory, not conversion metrics",
+      "context": "Google Ads Transparency does not expose performance data",
+      "solution": "Use count, repetition, and landing-page fit as outside signals.",
+      "severity": "medium"
+    }
+  ],
+  "steps": [
+    {
+      "action": "navigate",
+      "url": "https://adstransparency.google.com/?region=IN&domain={DOMAIN}",
+      "description": "Open the Ads Transparency Center for the domain",
+      "verify": "input.input.input-area",
+      "verifyTimeoutMs": 15000
+    },
+    {
+      "action": "wait",
+      "ms": 1500,
+      "description": "Wait for the domain results page"
+    },
+    {
+      "action": "browser_js",
+      "code": "(() => { const button = [...document.querySelectorAll('material-button, button, [role=\"button\"]')].find((el) => (el.innerText || '').includes('See all ads')); if (!button) return { expanded: false }; button.click(); return { expanded: true }; })()",
+      "description": "Expand the ad grid when See all ads is available",
+      "optional": true
+    },
+    {
+      "action": "wait",
+      "ms": 1000,
+      "description": "Allow the grid to settle after expansion",
+      "optional": true
+    },
+    {
+      "action": "browser_js",
+      "code": "(() => { const text = document.body.innerText; const adCount = text.match(/\\b\\d+ ads\\b/i)?.[0] || null; const advertisers = [...new Set([...document.querySelectorAll(\"a[href*='/advertiser/']\")].map((el) => (el.textContent || '').trim()).filter(Boolean))].slice(0, 10); const creativeLinks = [...document.querySelectorAll(\"a[href*='/advertiser/'][href*='/creative/']\")].map((el) => el.href).slice(0, 20); return { domain: `{DOMAIN}`, url: location.href, adCount, advertisers, creativeLinks }; })()",
+      "description": "Extract ad count, advertiser labels, and creative links"
+    },
+    {
+      "action": "screenshot",
+      "description": "Capture the Google ad results page",
+      "optional": true
+    }
+  ]
+}

package/dist-playbooks/google-search-competitor-research.json

@@ -0,0 +1,76 @@
+{
+  "id": "google-search-competitor-research",
+  "name": "Google Search — Competitor Discovery",
+  "description": "Open a Google Search results page and extract the top visible competitor headings and result domains.",
+  "platform": "google-search-competitor-research",
+  "version": "1.0.0",
+  "urlPatterns": [
+    "*google.com/search*"
+  ],
+  "tags": [
+    "google",
+    "search",
+    "competitor-research",
+    "browser",
+    "cdp"
+  ],
+  "successCount": 0,
+  "failCount": 0,
+  "urls": {
+    "search": "https://www.google.com/search?q={QUERY}"
+  },
+  "selectors": {
+    "search": {
+      "query_field": "textarea#APjFqb"
+    },
+    "results": {
+      "headings": "h3",
+      "links": "a[href]"
+    }
+  },
+  "flows": {
+    "market_query": {
+      "steps": [
+        "Open a direct search URL",
+        "Read the top headings and associated domains",
+        "Use repeated brand presence across multiple queries as a signal"
+      ],
+      "why": "Search is the fastest way to discover who owns the category language before validating paid inventory."
+    }
+  },
+  "detection": {
+    "on_search": "location.hostname.includes('google.com') && location.pathname === '/search'"
+  },
+  "errors": [
+    {
+      "error": "Google result layouts vary",
+      "context": "AI Overviews and media modules can change the page structure",
+      "solution": "Extract visible headings and domains rather than assuming exact result positions.",
+      "severity": "medium"
+    }
+  ],
+  "steps": [
+    {
+      "action": "navigate",
+      "url": "https://www.google.com/search?q={QUERY}",
+      "description": "Open the market search query",
+      "verify": "textarea#APjFqb",
+      "verifyTimeoutMs": 15000
+    },
+    {
+      "action": "wait",
+      "ms": 1500,
+      "description": "Wait for results to render"
+    },
+    {
+      "action": "browser_js",
+      "code": "(() => { const headings = [...document.querySelectorAll('h3')].map((el) => (el.textContent || '').trim()).filter(Boolean).slice(0, 10); const links = [...document.querySelectorAll('a[href]')].map((el) => ({ text: (el.textContent || '').trim(), href: el.href })).filter((item) => item.text || item.href.includes('/url?')).slice(0, 20); return { query: `{QUERY}`, url: location.href, headings, links }; })()",
+      "description": "Extract the top visible headings and result links"
+    },
+    {
+      "action": "screenshot",
+      "description": "Capture the search results page",
+      "optional": true
+    }
+  ]
+}

package/dist-playbooks/keynote-add-slide.json

@@ -0,0 +1,20 @@
+{
+  "id": "keynote-add-slide",
+  "name": "add-slide",
+  "description": "Add a new slide at the end of the front Keynote document with a title and body text",
+  "platform": "keynote",
+  "version": "1.0.0",
+  "tags": [
+    "keynote",
+    "recorded"
+  ],
+  "successCount": 0,
+  "failCount": 0,
+  "steps": [
+    {
+      "action": "applescript",
+      "script": "tell application \"Keynote\"\n    tell front document\n        set newSlide to make new slide at end of slides\n        tell newSlide\n            set object text of default title item to \"New Slide Title\"\n            set object text of default body item to \"Bullet point content\"\n        end tell\n        return \"Added slide \" & (slide number of newSlide) & \" with title\"\n    end tell\nend tell",
+      "description": "AppleScript: tell application \"Keynote\"\n    tell front document\n        set newSlide to make ..."
+    }
+  ]
+}

package/dist-playbooks/keynote-create-presentation.json

@@ -0,0 +1,20 @@
+{
+  "id": "keynote-create-presentation",
+  "name": "create-presentation",
+  "description": "Create a new Keynote presentation with a theme and set the title slide text",
+  "platform": "keynote",
+  "version": "1.0.0",
+  "tags": [
+    "keynote",
+    "recorded"
+  ],
+  "successCount": 0,
+  "failCount": 0,
+  "steps": [
+    {
+      "action": "applescript",
+      "script": "tell application \"Keynote\"\n    -- Create a new presentation with a theme\n    set newDoc to make new document with properties {document theme: theme id \"[TOKEN_REDACTED]\" of application \"Keynote\"}\n    tell newDoc\n        tell slide 1\n            set object text of default title item to \"New Presentation\"\n            set object text of default body item to \"Created via automation\"\n        end tell\n    end tell\n    set docName to name of newDoc\n    -- Close it to demonstrate the workflow\n    close newDoc saving no\n    return \"Created: \" & docName\nend tell",
+      "description": "AppleScript: tell application \"Keynote\"\n    -- Create a new presentation with a theme\n    set..."
+    }
+  ]
+}

package/dist-playbooks/keynote-export-pdf.json

@@ -0,0 +1,20 @@
+{
+  "id": "keynote-export-pdf",
+  "name": "export-pdf",
+  "description": "Export the front Keynote document as a PDF to /tmp",
+  "platform": "keynote",
+  "version": "1.0.0",
+  "tags": [
+    "keynote",
+    "recorded"
+  ],
+  "successCount": 0,
+  "failCount": 0,
+  "steps": [
+    {
+      "action": "applescript",
+      "script": "tell application \"Keynote\"\n    tell front document\n        export to POSIX file \"/tmp/keynote-export.pdf\" as PDF\n    end tell\n    return \"Exported to /tmp/keynote-export.pdf\"\nend tell",
+      "description": "AppleScript: tell application \"Keynote\"\n    tell front document\n        export to POSIX file ..."
+    }
+  ]
+}

package/dist-playbooks/keynote-play-slideshow.json

@@ -0,0 +1,20 @@
+{
+  "id": "keynote-play-slideshow",
+  "name": "play-slideshow",
+  "description": "Start and stop a Keynote slideshow presentation via AppleScript",
+  "platform": "keynote",
+  "version": "1.0.0",
+  "tags": [
+    "keynote",
+    "recorded"
+  ],
+  "successCount": 0,
+  "failCount": 0,
+  "steps": [
+    {
+      "action": "applescript",
+      "script": "tell application \"Keynote\"\n    -- Start presentation (play slideshow)\n    start front document\nend tell",
+      "description": "AppleScript: tell application \"Keynote\"\n    -- Start presentation (play slideshow)\n    start ..."
+    }
+  ]
+}

package/dist-playbooks/meta-ad-library-competitor-research.json

@@ -0,0 +1,100 @@
+{
+  "id": "meta-ad-library-competitor-research",
+  "name": "Meta Ad Library — Competitor Research",
+  "description": "Open Meta Ad Library in India all-ads mode, search an advertiser page, and extract active campaign snippets.",
+  "platform": "meta-ad-library",
+  "version": "1.0.0",
+  "urlPatterns": [
+    "*facebook.com/ads/library*"
+  ],
+  "tags": [
+    "meta",
+    "facebook",
+    "ads-library",
+    "competitor-research",
+    "browser",
+    "cdp"
+  ],
+  "successCount": 0,
+  "failCount": 0,
+  "urls": {
+    "home": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=IN&is_targeted_country=false&media_type=all&search_type=keyword_unordered&sort_data[direction]=desc&sort_data[mode]=total_impressions"
+  },
+  "selectors": {
+    "search": {
+      "input": "input[placeholder='Search by keyword or advertiser']",
+      "suggestions": "[role='listbox']",
+      "page_option": "li[id^='pageID:'], [role='option']"
+    }
+  },
+  "flows": {
+    "advertiser_lookup": {
+      "steps": [
+        "Open the India all-ads library",
+        "Type the advertiser name",
+        "Click the matching advertiser suggestion",
+        "Extract results count, Library IDs, and visible ad snippets"
+      ],
+      "guards": [
+        "Use advertiser lookup first",
+        "Keep ad_type=all in the URL"
+      ],
+      "why": "This is the highest-signal Meta workflow for active competitor campaign review."
+    }
+  },
+  "detection": {
+    "on_library": "location.hostname.includes('facebook.com') && location.pathname.includes('/ads/library')"
+  },
+  "errors": [
+    {
+      "error": "keyword-only research undercounts advertisers",
+      "context": "Many brands do not lead copy with the category keyword",
+      "solution": "Run this playbook with ADVERTISER set to the page name and use keyword searches separately.",
+      "severity": "medium"
+    }
+  ],
+  "steps": [
+    {
+      "action": "navigate",
+      "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=IN&is_targeted_country=false&media_type=all&search_type=keyword_unordered&sort_data[direction]=desc&sort_data[mode]=total_impressions",
+      "description": "Open Meta Ad Library in India all-ads mode",
+      "verify": "input[placeholder='Search by keyword or advertiser']",
+      "verifyTimeoutMs": 15000
+    },
+    {
+      "action": "wait",
+      "ms": 1500,
+      "description": "Let the library UI settle"
+    },
+    {
+      "action": "browser_js",
+      "code": "(() => { const input = document.querySelector(\"input[placeholder='Search by keyword or advertiser']\"); if (!(input instanceof HTMLInputElement)) throw new Error('Meta Ad Library search input not found'); const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')?.set; if (!setter) throw new Error('HTMLInputElement value setter unavailable'); setter.call(input, `{ADVERTISER}`); input.dispatchEvent(new Event('input', { bubbles: true })); input.dispatchEvent(new Event('change', { bubbles: true })); input.focus(); return { typed: input.value }; })()",
+      "description": "Type the advertiser page name"
+    },
+    {
+      "action": "wait",
+      "ms": 1500,
+      "description": "Wait for advertiser suggestions"
+    },
+    {
+      "action": "browser_js",
+      "code": "(() => { const wanted = `{ADVERTISER}`.trim().toLowerCase(); const option = [...document.querySelectorAll(\"li[id^='pageID:'], [role='option']\")].find((el) => (el.innerText || '').toLowerCase().includes(wanted)); if (!option) throw new Error(`Advertiser option not found: ${wanted}`); option.click(); return { clicked: (option.innerText || '').trim() }; })()",
+      "description": "Open the matching advertiser page"
+    },
+    {
+      "action": "wait",
+      "ms": 2500,
+      "description": "Wait for advertiser results to load"
+    },
+    {
+      "action": "browser_js",
+      "code": "(() => { const text = document.body.innerText; const results = text.match(/~\\d+ results/)?.[0] || null; const snippets = text.split(/Active\\nLibrary ID:/).slice(1, 7).map((chunk) => (`Library ID:${chunk}`).slice(0, 1400)); return { advertiser: `{ADVERTISER}`, url: location.href, results, snippets }; })()",
+      "description": "Extract visible active ad snippets and result count"
+    },
+    {
+      "action": "screenshot",
+      "description": "Capture the advertiser results page",
+      "optional": true
+    }
+  ]
+}