@champpaba/gslide 0.1.0

package/bin/gslide.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = join(__dirname, "..");
+const venvBin = join(pkgRoot, ".venv", "bin");
+const gslideExe = join(venvBin, "gslide");
+
+if (!existsSync(gslideExe)) {
+  console.error("gslide Python package not installed.");
+  console.error("Run: npm rebuild @ChampPABA/gslide");
+  process.exit(1);
+}
+
+const args = process.argv.slice(2);
+const child = spawn(gslideExe, args, {
+  stdio: "inherit",
+  env: { ...process.env, PATH: `${venvBin}:${process.env.PATH}` },
+});
+
+child.on("close", (code) => process.exit(code ?? 1));
+child.on("error", (err) => {
+  console.error(`Failed to start gslide: ${err.message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@champpaba/gslide",
+  "version": "0.1.0",
+  "description": "CLI tool for automating Google Slides 'Help me visualize' feature via browser automation",
+  "bin": {
+    "gslide": "./bin/gslide.mjs"
+  },
+  "scripts": {
+    "postinstall": "bash scripts/postinstall.sh"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "src/",
+    "pyproject.toml"
+  ],
+  "keywords": [
+    "google-slides",
+    "presentation",
+    "gemini",
+    "browser-automation",
+    "playwright"
+  ],
+  "author": "ChampPABA",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ChampPABA/gslide.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=16"
+  }
+}

package/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "gslide"
+version = "0.1.0"
+description = "CLI tool for automating Google Slides 'Help me visualize' feature via browser automation"
+requires-python = ">=3.10"
+dependencies = [
+    "playwright>=1.40.0",
+    "click>=8.1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-cov>=4.1.0",
+]
+
+[project.scripts]
+gslide = "gslide.cli:cli"
+
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--tb=short -q"

package/scripts/postinstall.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+set -e
+
+PKG_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+VENV_DIR="$PKG_DIR/.venv"
+UV_BIN=""
+
+echo "Installing gslide..."
+
+# Step 1: Check/install uv
+echo "  [1/4] Checking uv..."
+if command -v uv &>/dev/null; then
+    UV_BIN="$(command -v uv)"
+    echo "         found: $UV_BIN"
+else
+    echo "         not found, installing..."
+    curl -LsSf https://astral.sh/uv/install.sh | sh 2>/dev/null
+    export PATH="$HOME/.local/bin:$PATH"
+    if command -v uv &>/dev/null; then
+        UV_BIN="$(command -v uv)"
+        echo "         installed: $UV_BIN"
+    else
+        echo "         ERROR: Failed to install uv. Install manually: https://docs.astral.sh/uv/"
+        exit 1
+    fi
+fi
+
+# Step 2: Check/install Python
+echo "  [2/4] Checking Python 3.10+..."
+PYTHON_VERSION=$("$UV_BIN" python find 3.10 2>/dev/null || true)
+if [ -z "$PYTHON_VERSION" ]; then
+    echo "         not found, installing via uv..."
+    "$UV_BIN" python install 3.10 2>/dev/null
+    PYTHON_VERSION=$("$UV_BIN" python find 3.10 2>/dev/null || true)
+fi
+if [ -z "$PYTHON_VERSION" ]; then
+    echo "         ERROR: Could not install Python 3.10+."
+    exit 1
+fi
+echo "         found: $PYTHON_VERSION"
+
+# Step 3: Create venv and install gslide
+echo "  [3/4] Installing gslide package..."
+if [ ! -d "$VENV_DIR" ]; then
+    "$UV_BIN" venv "$VENV_DIR" --python 3.10 2>/dev/null
+fi
+"$UV_BIN" pip install --python "$VENV_DIR/bin/python" -e "$PKG_DIR" 2>/dev/null
+echo "         done"
+
+# Step 4: Install Playwright Chromium
+echo "  [4/4] Installing Chromium browser..."
+PLAYWRIGHT_BIN="$VENV_DIR/bin/playwright"
+if [ -f "$PLAYWRIGHT_BIN" ]; then
+    "$PLAYWRIGHT_BIN" install chromium 2>/dev/null
+    echo "         done"
+else
+    echo "         WARNING: playwright not found, skipping Chromium install"
+    echo "         Run manually: $VENV_DIR/bin/playwright install chromium"
+fi
+
+echo ""
+echo "Ready! Run: gslide auth login"

package/src/gslide/__init__.py

@@ -0,0 +1,3 @@
+"""gslide — CLI for automating Google Slides 'Help me visualize' feature."""
+
+__version__ = "0.1.0"

package/src/gslide/auth.py

@@ -0,0 +1,95 @@
+"""Authentication session management — file I/O and browser operations."""
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+import click
+
+
+SLIDES_URL = "https://docs.google.com/presentation/"
+
+
+def get_storage_path() -> Path:
+    """Return the path to the storage state file."""
+    return Path.home() / ".gslide" / "storage_state.json"
+
+
+def is_logged_in() -> bool:
+    """Check if a storage state file exists."""
+    return get_storage_path().exists()
+
+
+def save_storage_state(data: dict[str, Any]) -> None:
+    """Save storage state data to disk, creating directories as needed."""
+    path = get_storage_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2))
+
+
+def delete_storage_state() -> None:
+    """Delete the storage state file. No error if missing."""
+    try:
+        get_storage_path().unlink()
+    except FileNotFoundError:
+        pass
+
+
+def login() -> None:
+    """Launch headed browser for Google login, save storage state on success."""
+    from gslide.browser import BrowserSession, save_session
+
+    click.echo("Opening browser for Google login...")
+    click.echo("")
+    click.echo("Instructions:")
+    click.echo("1. Complete the Google login in the browser window")
+    click.echo("2. Wait until you see Google Slides homepage")
+    click.echo("3. Press ENTER here to save and close")
+    click.echo("")
+
+    with BrowserSession(headed=True) as context:
+        page = context.new_page()
+        page.goto(SLIDES_URL)
+
+        try:
+            input("[Press ENTER when logged in] ")
+        except (KeyboardInterrupt, EOFError):
+            click.echo("\nAborted.", err=True)
+            sys.exit(1)
+
+        save_session(context, get_storage_path())
+        click.echo("Session saved.")
+
+
+def status() -> None:
+    """Check if saved session is still valid."""
+    path = get_storage_path()
+
+    if not path.exists():
+        click.echo("Not logged in. Run: gslide auth login")
+        sys.exit(1)
+
+    from gslide.browser import BrowserSession
+
+    with BrowserSession(headed=False, storage_state=path) as context:
+        page = context.new_page()
+        page.goto(SLIDES_URL, wait_until="domcontentloaded")
+        # Google Slides never reaches networkidle — wait for redirect or UI instead
+        page.wait_for_timeout(5000)
+
+        if "accounts.google.com" in page.url:
+            click.echo("Session expired. Run: gslide auth login")
+            sys.exit(1)
+
+        click.echo("Session valid.")
+
+
+def logout() -> None:
+    """Delete saved session."""
+    if not is_logged_in():
+        click.echo("Not logged in.")
+        return
+
+    delete_storage_state()
+    click.echo("Logged out.")

package/src/gslide/browser.py

@@ -0,0 +1,41 @@
+"""Playwright browser lifecycle management."""
+
+from pathlib import Path
+from typing import Any
+
+from playwright.sync_api import sync_playwright, BrowserContext, Playwright
+
+
+class BrowserSession:
+    """Manages a Playwright browser context with optional storage state."""
+
+    def __init__(self, headed: bool = False, storage_state: Path | None = None) -> None:
+        self._headed = headed
+        self._storage_state = storage_state
+        self._pw: Playwright | None = None
+        self._context: BrowserContext | None = None
+
+    def __enter__(self) -> BrowserContext:
+        self._pw = sync_playwright().start()
+        browser = self._pw.chromium.launch(headless=not self._headed)
+
+        context_opts: dict[str, Any] = {}
+        if self._storage_state and self._storage_state.exists():
+            context_opts["storage_state"] = str(self._storage_state)
+
+        self._context = browser.new_context(**context_opts)
+        return self._context
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        if self._context:
+            self._context.close()
+            self._context.browser.close()
+        if self._pw:
+            self._pw.stop()
+        return None
+
+
+def save_session(context: BrowserContext, path: Path) -> None:
+    """Export browser context storage state to a file."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    context.storage_state(path=str(path))

package/src/gslide/cli.py

@@ -0,0 +1,178 @@
+"""Click CLI entry point for gslide."""
+
+import sys
+from pathlib import Path
+
+import click
+
+
+@click.group()
+def cli() -> None:
+    """gslide — Automate Google Slides 'Help me visualize' feature."""
+
+
+@cli.command()
+def update() -> None:
+    """Check for updates and self-update via npm."""
+    import subprocess
+
+    from gslide import __version__
+
+    click.echo(f"Current version: v{__version__}")
+    click.echo("Checking for updates...")
+
+    try:
+        result = subprocess.run(
+            ["npm", "view", "@ChampPABA/gslide", "version"],
+            capture_output=True,
+            text=True,
+            timeout=15,
+        )
+        latest = result.stdout.strip()
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        click.echo("Could not check npm registry.", err=True)
+        sys.exit(1)
+
+    if not latest:
+        click.echo("Could not determine latest version.", err=True)
+        sys.exit(1)
+
+    if latest == __version__:
+        click.echo(f"Already up to date (v{__version__}).")
+        return
+
+    click.echo(f"Latest version: v{latest}")
+    click.echo("Updating...")
+
+    proc = subprocess.run(
+        ["npm", "update", "-g", "@ChampPABA/gslide"],
+        timeout=120,
+    )
+    if proc.returncode == 0:
+        click.echo(f"Updated to v{latest}.")
+    else:
+        click.echo("Update failed.", err=True)
+        sys.exit(1)
+
+
+# --- Auth commands ---
+
+
+@cli.group()
+def auth() -> None:
+    """Manage Google authentication session."""
+
+
+@auth.command()
+def login() -> None:
+    """Launch browser for Google login."""
+    from gslide.auth import login as do_login
+
+    do_login()
+
+
+@auth.command()
+def status() -> None:
+    """Check if saved session is valid."""
+    from gslide.auth import status as do_status
+
+    do_status()
+
+
+@auth.command()
+def logout() -> None:
+    """Delete saved session."""
+    from gslide.auth import logout as do_logout
+
+    do_logout()
+
+
+# --- Gen commands ---
+
+
+@cli.group()
+def gen() -> None:
+    """Generate slides, infographics, and images."""
+
+
+def _common_gen_options(f):
+    """Shared options for single-gen commands."""
+    f = click.option("--presentation", required=True, help="Presentation ID or URL")(f)
+    f = click.option("--prompt", required=True, help="Generation prompt")(f)
+    f = click.option("--timeout", default=120, type=int, help="Timeout in seconds")(f)
+    return f
+
+
+@gen.command()
+@_common_gen_options
+def infographic(presentation: str, prompt: str, timeout: int) -> None:
+    """Generate an infographic slide."""
+    from gslide.gen import gen_single
+
+    gen_single(presentation, "infographic", prompt, timeout=timeout)
+
+
+@gen.command()
+@_common_gen_options
+def slide(presentation: str, prompt: str, timeout: int) -> None:
+    """Generate a slide."""
+    from gslide.gen import gen_single
+
+    gen_single(presentation, "slide", prompt, timeout=timeout)
+
+
+@gen.command()
+@_common_gen_options
+@click.option("--slide-index", required=True, type=int, help="Target slide index")
+@click.option(
+    "--insert-as",
+    default="image",
+    type=click.Choice(["image", "background"]),
+    help="Insert as image or background",
+)
+def image(
+    presentation: str,
+    prompt: str,
+    timeout: int,
+    slide_index: int,
+    insert_as: str,
+) -> None:
+    """Generate and insert an image on a slide."""
+    from gslide.gen import gen_single
+
+    gen_single(
+        presentation,
+        "image",
+        prompt,
+        timeout=timeout,
+        slide_index=slide_index,
+        insert_as=insert_as,
+    )
+
+
+@gen.command()
+@click.option("--file", "file_path", required=True, type=click.Path(exists=True), help="Path to prompts.json")
+@click.option("--continue-on-error", is_flag=True, help="Continue on individual slide errors")
+@click.option("--dry-run", is_flag=True, help="Validate and show summary without generating")
+@click.option("--timeout", default=60, type=int, help="Timeout per slide in seconds")
+def batch(file_path: str, continue_on_error: bool, dry_run: bool, timeout: int) -> None:
+    """Generate slides from a prompts.json file."""
+    from gslide.prompts import load_prompts, ValidationError
+
+    try:
+        prompts_data = load_prompts(Path(file_path))
+    except ValidationError as e:
+        click.echo(f"Validation error: {e}", err=True)
+        sys.exit(1)
+
+    if dry_run:
+        tabs_used = {s.tab for s in prompts_data.slides}
+        click.echo(f"Presentation: {prompts_data.presentation_id}")
+        click.echo(f"Slides: {len(prompts_data.slides)}")
+        click.echo(f"Images: {len(prompts_data.images)}")
+        click.echo(f"Tabs: {', '.join(sorted(tabs_used))}")
+        return
+
+    from gslide.gen import gen_batch
+
+    gen_batch(prompts_data, continue_on_error=continue_on_error, timeout=timeout)

package/src/gslide/gen.py

@@ -0,0 +1,446 @@
+"""Generation logic — browser automation for 'Help me visualize' feature.
+
+Selector discoveries (validated Mar 19, 2026):
+- Panel opener: div[aria-label="Help me visualize"] (right sidebar icon)
+- Tabs: role="tab" with name="Slide"/"Image"/"Infographic"
+- Text input: visible textarea (use keyboard.type, not fill)
+- Submit: get_by_role("button", name="Create", exact=True)
+- Filmstrip: [aria-label="filmstrip"] (takes ~10s to appear)
+- Generation takes 30-60s, shows "Creating..." tooltip
+- Insert buttons appear after generation completes (below preview)
+"""
+
+import sys
+import time
+
+import click
+from playwright.sync_api import Page, TimeoutError as PwTimeout
+
+from gslide.auth import get_storage_path
+from gslide.browser import BrowserSession
+from gslide.prompts import PromptsData
+
+
+PRESENTATION_URL = "https://docs.google.com/presentation/d/{id}/edit"
+DEFAULT_TIMEOUT_MS = 120_000  # 120s — generation can take 30-60s
+PANEL_LOAD_TIMEOUT_MS = 10_000
+SLIDES_LOAD_TIMEOUT_MS = 30_000
+
+
+class GenerationError(Exception):
+    """Raised when slide generation fails."""
+
+
+# --- Navigation & Panel ---
+
+
+def navigate_to_presentation(page: Page, presentation_id: str) -> None:
+    """Load presentation, wait for UI, check auth."""
+    url = PRESENTATION_URL.format(id=presentation_id)
+    page.goto(url, wait_until="domcontentloaded")
+
+    # Google Slides is heavy — give it time, check for auth redirect
+    page.wait_for_timeout(5000)
+
+    if "accounts.google.com" in page.url:
+        raise GenerationError("Session expired. Run: gslide auth login")
+
+    if presentation_id not in page.url:
+        raise GenerationError("Cannot access presentation")
+
+    # Wait for filmstrip sidebar to confirm Slides UI loaded
+    try:
+        page.wait_for_selector(
+            '[aria-label="filmstrip"]', timeout=SLIDES_LOAD_TIMEOUT_MS
+        )
+    except PwTimeout:
+        raise GenerationError("Google Slides UI did not load in time")
+
+
+def open_panel(page: Page) -> None:
+    """Navigate to last slide and open 'Help me visualize' panel."""
+    page.keyboard.press("End")
+    page.wait_for_timeout(500)
+
+    # Click the "Help me visualize" sidebar icon (div, not button)
+    hmv = page.locator('div[aria-label="Help me visualize"]')
+    hmv.click()
+
+    # Wait for the panel to appear — tabs and textarea become visible
+    page.wait_for_selector('[role="tab"]', timeout=PANEL_LOAD_TIMEOUT_MS)
+
+
+def _reopen_panel(page: Page, retries: int = 2) -> None:
+    """Reopen the HMV panel after insert overlay is dismissed.
+
+    After inserting a slide, the panel may close. This clicks the HMV icon
+    and waits for tabs to reappear, with retry logic.
+    """
+    for attempt in range(retries + 1):
+        try:
+            hmv = page.locator('div[aria-label="Help me visualize"]')
+            hmv.click()
+            page.wait_for_selector('[role="tab"]', timeout=PANEL_LOAD_TIMEOUT_MS)
+            return
+        except (PwTimeout, Exception):
+            if attempt < retries:
+                page.wait_for_timeout(1000)
+                continue
+            raise GenerationError("Failed to reopen HMV panel after insert")
+
+
+def select_tab(page: Page, tab_name: str) -> None:
+    """Click the tab (Slide/Infographic/Image) in the panel."""
+    tab = page.get_by_role("tab", name=tab_name)
+    tab.click()
+    page.wait_for_timeout(300)
+
+
+def _find_visible_textarea(page: Page) -> object:
+    """Find the first visible textarea in the panel."""
+    textareas = page.locator("textarea")
+    for i in range(textareas.count()):
+        ta = textareas.nth(i)
+        if ta.is_visible():
+            return ta
+    raise GenerationError("No visible text input found in panel")
+
+
+def _snapshot_preview_srcs(page: Page) -> set[str]:
+    """Capture current preview image src URLs to detect stale previews."""
+    srcs: set[str] = set()
+    preview = page.locator('img[src*="googleusercontent.com"]')
+    for i in range(preview.count()):
+        try:
+            src = preview.nth(i).get_attribute("src") or ""
+            if src:
+                srcs.add(src[:80])
+        except Exception:
+            continue
+    return srcs
+
+
+def fill_and_create(
+    page: Page, prompt: str, timeout_ms: int = DEFAULT_TIMEOUT_MS
+) -> None:
+    """Type prompt, click Create, wait for NEW preview image to appear.
+
+    Validated flow (Mar 19, 2026):
+    - keyboard.type() triggers input events that enable the Create button
+    - Generation takes 30-55s, preview appears as img[src*="googleusercontent.com"]
+    - No Insert button appears automatically — must click preview first
+    - Must track stale preview URLs to avoid detecting previous generation's image
+    """
+    # Snapshot existing preview URLs BEFORE creating — used to detect stale images
+    stale_srcs = _snapshot_preview_srcs(page)
+
+    textarea = _find_visible_textarea(page)
+    textarea.click()
+    page.wait_for_timeout(200)
+
+    textarea.fill("")
+    page.keyboard.type(prompt, delay=10)
+    page.wait_for_timeout(500)
+
+    create_btn = page.get_by_role("button", name="Create", exact=True)
+    if not create_btn.is_enabled():
+        raise GenerationError("Create button is disabled — prompt may be too short")
+    create_btn.click()
+
+    # Poll for: NEW preview image appears OR error text
+    start = time.monotonic()
+    while (time.monotonic() - start) * 1000 < timeout_ms:
+        page.wait_for_timeout(5000)
+
+        # Check for error
+        error_text = page.get_by_text("We didn't quite get that", exact=False)
+        if error_text.count() > 0 and error_text.first.is_visible():
+            raise GenerationError(
+                "Generation failed: prompt too vague — try a more detailed prompt"
+            )
+
+        # Check for NEW preview image (not in stale_srcs)
+        preview = page.locator('img[src*="googleusercontent.com"]')
+        for i in range(preview.count()):
+            try:
+                img = preview.nth(i)
+                if img.is_visible():
+                    bb = img.bounding_box()
+                    src = (img.get_attribute("src") or "")[:80]
+                    if bb and bb["width"] > 200 and src not in stale_srcs:
+                        return  # NEW preview appeared — generation complete
+            except Exception:
+                continue
+
+    raise GenerationError(f"Generation timed out after {timeout_ms // 1000}s")
+
+
+# --- Tab-specific insert logic ---
+
+
+def _click_preview_image(page: Page) -> None:
+    """Click the generated preview image to open the insert overlay.
+
+    Validated flow: after generation, the preview appears as an img hosted on
+    googleusercontent.com. Clicking it opens a fullscreen preview with
+    "Insert on new slide" button.
+    """
+    preview = page.locator('img[src*="googleusercontent.com"]')
+    for i in range(preview.count()):
+        try:
+            img = preview.nth(i)
+            if img.is_visible():
+                bb = img.bounding_box()
+                if bb and bb["width"] > 200:
+                    page.mouse.click(
+                        bb["x"] + bb["width"] / 2,
+                        bb["y"] + bb["height"] / 2,
+                    )
+                    page.wait_for_timeout(2000)
+                    return
+        except Exception:
+            continue
+    raise GenerationError("Generated preview image not found")
+
+
+def insert_infographic(page: Page) -> None:
+    """Click preview → 'Insert on new slide' for infographic tab."""
+    _click_preview_image(page)
+
+    btn = page.get_by_text("Insert on new slide")
+    if btn.count() > 0 and btn.first.is_visible():
+        btn.first.click()
+    else:
+        raise GenerationError("'Insert on new slide' button not found after clicking preview")
+    _wait_for_new_slide(page)
+
+
+def insert_slide(page: Page) -> None:
+    """Click preview → 'Insert on new slide' for slide tab."""
+    _click_preview_image(page)
+
+    # Slide tab uses same "Insert on new slide" button after clicking preview
+    btn = page.get_by_text("Insert on new slide")
+    if btn.count() > 0 and btn.first.is_visible():
+        btn.first.click()
+    else:
+        raise GenerationError("'Insert on new slide' button not found for slide tab")
+    _wait_for_new_slide(page)
+
+
+def insert_image(page: Page, insert_as: str = "image") -> None:
+    """Click preview → insert as image or background."""
+    _click_preview_image(page)
+
+    # Image tab may show different insert options via dropdown
+    if insert_as == "background":
+        option_text = "Insert as background"
+    else:
+        option_text = "Insert as image"
+
+    btn = page.get_by_text(option_text)
+    if btn.count() > 0 and btn.first.is_visible():
+        btn.first.click()
+    else:
+        # Fallback: try "Insert on new slide" or dropdown
+        fallback = page.get_by_text("Insert on new slide")
+        if fallback.count() > 0 and fallback.first.is_visible():
+            fallback.first.click()
+        else:
+            raise GenerationError(f"'{option_text}' button not found")
+
+    page.wait_for_timeout(2000)
+
+
+
+def check_url(page: Page, presentation_id: str) -> None:
+    """Verify browser URL still contains the target presentation ID."""
+    if presentation_id not in page.url:
+        raise GenerationError("Browser navigated away from target presentation")
+
+
+def _wait_for_new_slide(page: Page) -> None:
+    """Wait for new slide to appear in filmstrip."""
+    page.wait_for_timeout(2000)
+
+
+# --- Orchestration ---
+
+
+_INSERT_FN = {
+    "infographic": lambda page, **_: insert_infographic(page),
+    "slide": lambda page, **_: insert_slide(page),
+    "image": lambda page, **opts: insert_image(page, opts.get("insert_as", "image")),
+}
+
+
+def gen_single(
+    presentation_id: str,
+    tab: str,
+    prompt: str,
+    *,
+    timeout: int = 120,
+    slide_index: int | None = None,
+    insert_as: str = "image",
+) -> None:
+    """Generate a single slide/infographic/image via browser automation."""
+    storage_path = get_storage_path()
+    if not storage_path.exists():
+        click.echo("Not logged in. Run: gslide auth login", err=True)
+        sys.exit(1)
+
+    timeout_ms = timeout * 1000
+
+    with BrowserSession(storage_state=storage_path) as context:
+        page = context.new_page()
+
+        try:
+            navigate_to_presentation(page, presentation_id)
+            check_url(page, presentation_id)
+
+            if tab == "image" and slide_index is not None:
+                _navigate_to_slide(page, slide_index)
+            else:
+                open_panel(page)
+
+            select_tab(page, tab.capitalize())
+            fill_and_create(page, prompt, timeout_ms=timeout_ms)
+            check_url(page, presentation_id)
+
+            insert_fn = _INSERT_FN[tab]
+            insert_fn(page, insert_as=insert_as)
+
+            check_url(page, presentation_id)
+            click.echo(f"Done: {tab} generated successfully.")
+
+        except GenerationError as e:
+            click.echo(f"Error: {e}", err=True)
+            # Take screenshot for debugging
+            try:
+                page.screenshot(path="/tmp/gslide_error.png")
+                click.echo("Debug screenshot saved to /tmp/gslide_error.png")
+            except Exception:
+                pass
+            sys.exit(2)
+
+
+def _navigate_to_slide(page: Page, slide_index: int) -> None:
+    """Navigate to a specific slide by index and open panel."""
+    slides = page.locator('[aria-label="filmstrip"] [role="listitem"]')
+    if slide_index <= slides.count():
+        slides.nth(slide_index - 1).click()
+        page.wait_for_timeout(500)
+
+    open_panel(page)
+
+
+# --- Batch ---
+
+
+def gen_batch(
+    prompts_data: PromptsData,
+    *,
+    continue_on_error: bool = False,
+    timeout: int = 120,
+) -> None:
+    """Generate all slides from prompts data in a single browser session."""
+    storage_path = get_storage_path()
+    if not storage_path.exists():
+        click.echo("Not logged in. Run: gslide auth login", err=True)
+        sys.exit(1)
+
+    timeout_ms = timeout * 1000
+    total_slides = len(prompts_data.slides)
+    total_images = len(prompts_data.images)
+    errors: list[tuple[int, str, str]] = []
+    start_time = time.monotonic()
+
+    with BrowserSession(storage_state=storage_path) as context:
+        page = context.new_page()
+
+        try:
+            navigate_to_presentation(page, prompts_data.presentation_id)
+            open_panel(page)
+        except GenerationError as e:
+            click.echo(f"Error: {e}", err=True)
+            sys.exit(2)
+
+        current_tab: str | None = None
+
+        # Phase 1: Generate slides
+        for i, slide in enumerate(prompts_data.slides, 1):
+            label = f"[{i}/{total_slides}]"
+            click.echo(f"  {label} {slide.tab}: {slide.prompt[:50]}...")
+
+            try:
+                check_url(page, prompts_data.presentation_id)
+
+                if slide.tab != current_tab:
+                    select_tab(page, slide.tab.capitalize())
+                    current_tab = slide.tab
+
+                t0 = time.monotonic()
+                fill_and_create(page, slide.prompt, timeout_ms=timeout_ms)
+
+                insert_fn = _INSERT_FN[slide.tab]
+                insert_fn(page)
+
+                elapsed = time.monotonic() - t0
+                click.echo(f"  {label} done ({elapsed:.1f}s)")
+
+                # Return to last slide and reopen panel for next generation
+                page.keyboard.press("End")
+                page.wait_for_timeout(500)
+
+                # Close any lingering insert overlay, then reopen HMV panel
+                page.keyboard.press("Escape")
+                page.wait_for_timeout(500)
+                _reopen_panel(page)
+
+            except (GenerationError, PwTimeout, Exception) as e:
+                errors.append((i, slide.tab, str(e)))
+                click.echo(f"  {label} FAILED: {e}")
+                if not continue_on_error:
+                    break
+
+        # Phase 2: Generate images
+        for i, img in enumerate(prompts_data.images, 1):
+            label = f"[img {i}/{total_images}]"
+            click.echo(f"  {label} slide {img.target_slide}: {img.prompt[:50]}...")
+
+            try:
+                check_url(page, prompts_data.presentation_id)
+                _navigate_to_slide(page, img.target_slide)
+
+                if "image" != current_tab:
+                    select_tab(page, "Image")
+                    current_tab = "image"
+
+                t0 = time.monotonic()
+                fill_and_create(page, img.prompt, timeout_ms=timeout_ms)
+                insert_image(page, insert_as=img.insert_as)
+
+                elapsed = time.monotonic() - t0
+                click.echo(f"  {label} done ({elapsed:.1f}s)")
+
+            except (GenerationError, PwTimeout, Exception) as e:
+                errors.append((total_slides + i, "image", str(e)))
+                click.echo(f"  {label} FAILED: {e}")
+                if not continue_on_error:
+                    break
+
+
+    # Summary
+    total_elapsed = time.monotonic() - start_time
+    total_ops = total_slides + total_images
+    succeeded = total_ops - len(errors)
+
+    click.echo()
+    click.echo(f"Batch complete: {succeeded}/{total_ops} succeeded in {total_elapsed:.1f}s")
+    if errors:
+        click.echo(f"Failed ({len(errors)}):")
+        for idx, tab, err in errors:
+            click.echo(f"  #{idx} ({tab}): {err}")
+    click.echo(
+        f"Presentation: https://docs.google.com/presentation/d/{prompts_data.presentation_id}/edit"
+    )

package/src/gslide/prompts.py

@@ -0,0 +1,86 @@
+"""Load and validate prompts.json files for batch generation."""
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+class ValidationError(Exception):
+    """Raised when prompts.json validation fails."""
+
+
+VALID_TABS = frozenset({"slide", "infographic", "image"})
+
+
+@dataclass(frozen=True)
+class SlidePrompt:
+    tab: str
+    prompt: str
+
+
+@dataclass(frozen=True)
+class ImagePrompt:
+    target_slide: int
+    prompt: str
+    insert_as: str = "image"
+
+
+@dataclass(frozen=True)
+class PromptsData:
+    presentation_id: str
+    slides: list[SlidePrompt]
+    images: list[ImagePrompt] = field(default_factory=list)
+
+
+def load_prompts(path: Path) -> PromptsData:
+    """Load and validate a prompts.json file."""
+    with open(path) as f:
+        raw = json.load(f)
+
+    if not isinstance(raw, dict):
+        raise ValidationError("Prompts file must be a JSON object")
+
+    if "presentation_id" not in raw:
+        raise ValidationError("Missing required field: presentation_id")
+
+    if "slides" not in raw:
+        raise ValidationError("Missing required field: slides")
+
+    slides_raw = raw["slides"]
+    if not isinstance(slides_raw, list) or len(slides_raw) == 0:
+        raise ValidationError("slides must be a non-empty array")
+
+    slides: list[SlidePrompt] = []
+    for i, s in enumerate(slides_raw):
+        if "tab" not in s:
+            raise ValidationError(f"slides[{i}]: missing required field: tab")
+        if "prompt" not in s:
+            raise ValidationError(f"slides[{i}]: missing required field: prompt")
+        if s["tab"] not in VALID_TABS:
+            raise ValidationError(
+                f"slides[{i}]: invalid tab '{s['tab']}', must be one of: {', '.join(sorted(VALID_TABS))}"
+            )
+        slides.append(SlidePrompt(tab=s["tab"], prompt=s["prompt"]))
+
+    images: list[ImagePrompt] = []
+    for i, img in enumerate(raw.get("images", [])):
+        if "target_slide" not in img:
+            raise ValidationError(f"images[{i}]: missing required field: target_slide")
+        if "prompt" not in img:
+            raise ValidationError(f"images[{i}]: missing required field: prompt")
+        insert_as = img.get("insert_as", "image")
+        if insert_as not in ("image", "background"):
+            raise ValidationError(
+                f"images[{i}]: invalid insert_as '{insert_as}', must be 'image' or 'background'"
+            )
+        images.append(ImagePrompt(
+            target_slide=img["target_slide"],
+            prompt=img["prompt"],
+            insert_as=insert_as,
+        ))
+
+    return PromptsData(
+        presentation_id=raw["presentation_id"],
+        slides=slides,
+        images=images,
+    )

package/src/gslide.egg-info/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: gslide
+Version: 0.1.0
+Summary: CLI tool for automating Google Slides 'Help me visualize' feature via browser automation
+Requires-Python: >=3.10
+Requires-Dist: playwright>=1.40.0
+Requires-Dist: click>=8.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"

package/src/gslide.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+pyproject.toml
+src/gslide/__init__.py
+src/gslide/auth.py
+src/gslide/browser.py
+src/gslide/cli.py
+src/gslide/gen.py
+src/gslide/prompts.py
+src/gslide.egg-info/PKG-INFO
+src/gslide.egg-info/SOURCES.txt
+src/gslide.egg-info/dependency_links.txt
+src/gslide.egg-info/entry_points.txt
+src/gslide.egg-info/requires.txt
+src/gslide.egg-info/top_level.txt
+tests/test_auth.py
+tests/test_browser.py
+tests/test_cli.py
+tests/test_gen.py
+tests/test_prompts.py

package/src/gslide.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

package/src/gslide.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gslide = gslide.cli:cli

package/src/gslide.egg-info/requires.txt

@@ -0,0 +1,6 @@
+playwright>=1.40.0
+click>=8.1.0
+
+[dev]
+pytest>=7.4.0
+pytest-cov>=4.1.0

package/src/gslide.egg-info/top_level.txt

@@ -0,0 +1 @@
+gslide