@dfosco/storyboard 0.5.0-alpha.0

package/scaffold/preview.yml

@@ -0,0 +1,181 @@
+name: Deploy branch preview
+
+on:
+  push:
+    branches-ignore:
+      - main
+      - gh-pages
+  delete:
+
+concurrency:
+  group: gh-pages-deploy
+  cancel-in-progress: false
+
+jobs:
+  deploy-preview:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout source
+        uses: actions/checkout@v6
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+
+      - name: Derive branch folder name
+        id: branch
+        run: |
+          # Sanitize branch name: replace non-alphanumeric chars with hyphens
+          BRANCH_NAME="${GITHUB_REF_NAME}"
+          SAFE_NAME=$(echo "$BRANCH_NAME" | sed 's/[^a-zA-Z0-9._-]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
+          FOLDER="branch--${SAFE_NAME}"
+
+          echo "folder=$FOLDER" >> "$GITHUB_OUTPUT"
+          echo "base=/${FOLDER}/" >> "$GITHUB_OUTPUT"
+          echo "Preview folder: $FOLDER"
+          echo "Base path: /${FOLDER}/"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build with custom base path
+        run: npm run build
+        env:
+          VITE_BASE_PATH: ${{ steps.branch.outputs.base }}
+
+      - name: Deploy preview to gh-pages
+        run: |
+          set -e
+          FOLDER="${{ steps.branch.outputs.folder }}"
+
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          git fetch origin gh-pages:gh-pages 2>/dev/null || true
+          DEPLOY_DIR=$(mktemp -d)
+          if git show-ref --verify --quiet refs/heads/gh-pages; then
+            git worktree add "$DEPLOY_DIR" gh-pages
+          else
+            git worktree add --orphan "$DEPLOY_DIR" gh-pages
+            rm -rf "$DEPLOY_DIR"/*
+          fi
+
+          # Replace only this branch's folder
+          cd "$DEPLOY_DIR"
+          rm -rf "$FOLDER"
+          mkdir -p "$FOLDER"
+          cp -r "$GITHUB_WORKSPACE/dist/." "$FOLDER/"
+
+          # Ensure .nojekyll exists at root (GitHub Pages ignores _-prefixed dirs without it)
+          touch .nojekyll
+
+          git add -A
+          git diff --cached --quiet && echo "No changes to deploy" && exit 0
+          git commit -m "Deploy preview: $FOLDER @ $(echo $GITHUB_SHA | head -c 7)"
+          git push origin gh-pages
+
+      - name: Generate branch manifest
+        run: |
+          set -e
+          # Remove stale worktrees from previous steps
+          git worktree list --porcelain | awk '/^worktree \/tmp/{print $2}' | while read wt; do
+            git worktree remove --force "$wt" 2>/dev/null || true
+          done
+          git fetch origin gh-pages:gh-pages 2>/dev/null || true
+          DEPLOY_DIR=$(mktemp -d)
+          git worktree add "$DEPLOY_DIR" gh-pages
+
+          cd "$DEPLOY_DIR"
+
+          echo '[' > branches.json
+          FIRST=true
+          for dir in branch--*/; do
+            [ -d "$dir" ] || continue
+            FOLDER="${dir%/}"
+            BRANCH="${FOLDER#branch--}"
+            if [ "$FIRST" = true ]; then
+              FIRST=false
+            else
+              echo ',' >> branches.json
+            fi
+            printf '  {"folder":"%s","branch":"%s"}' "$FOLDER" "$BRANCH" >> branches.json
+          done
+          echo '' >> branches.json
+          echo ']' >> branches.json
+
+          git add branches.json
+          git diff --cached --quiet && echo "Manifest unchanged" && exit 0
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git commit -m "Update branch manifest"
+          git push origin gh-pages
+
+      - name: Print preview URL
+        run: |
+          echo "## 🔗 Branch Preview" >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "Preview deployed at: ${{ steps.branch.outputs.base }}" >> "$GITHUB_STEP_SUMMARY"
+
+  cleanup-preview:
+    if: github.event_name == 'delete' && github.event.ref_type == 'branch'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout gh-pages
+        uses: actions/checkout@v6
+        with:
+          ref: gh-pages
+
+      - name: Remove branch preview folder
+        run: |
+          set -e
+          BRANCH_NAME="${{ github.event.ref }}"
+          SAFE_NAME=$(echo "$BRANCH_NAME" | sed 's/[^a-zA-Z0-9._-]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
+          FOLDER="branch--${SAFE_NAME}"
+
+          if [ -d "$FOLDER" ]; then
+            git config user.name "github-actions[bot]"
+            git config user.email "github-actions[bot]@users.noreply.github.com"
+
+            rm -rf "$FOLDER"
+            git add -A
+            git commit -m "Remove preview: $FOLDER"
+            git push origin gh-pages
+            echo "Removed preview: $FOLDER"
+          else
+            echo "No preview folder found for: $FOLDER"
+          fi
+
+      - name: Generate branch manifest
+        run: |
+          set -e
+
+          echo '[' > branches.json
+          FIRST=true
+          for dir in branch--*/; do
+            [ -d "$dir" ] || continue
+            FOLDER="${dir%/}"
+            BRANCH="${FOLDER#branch--}"
+            if [ "$FIRST" = true ]; then
+              FIRST=false
+            else
+              echo ',' >> branches.json
+            fi
+            printf '  {"folder":"%s","branch":"%s"}' "$FOLDER" "$BRANCH" >> branches.json
+          done
+          echo '' >> branches.json
+          echo ']' >> branches.json
+
+          git add branches.json
+          git diff --cached --quiet && echo "Manifest unchanged" && exit 0
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git commit -m "Update branch manifest"
+          git push origin gh-pages

package/scaffold/scripts/link.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# Link all @dfosco/* packages to local storyboard-core source.
+# Run from storyboard root: npm run link
+#
+# Prerequisites: run `npm run link` in storyboard-core first
+# to register the packages globally.
+#
+# IMPORTANT: npm install wipes symlinks. Always re-run this script
+# after any npm install in this repo.
+set -euo pipefail
+
+PACKAGES=(
+  "@dfosco/storyboard-core"
+  "@dfosco/storyboard-react"
+  "@dfosco/storyboard-react-primer"
+  "@dfosco/storyboard-react-reshaped"
+  "@dfosco/tiny-canvas"
+)
+
+echo "Linking local @dfosco/* packages..."
+npm link "${PACKAGES[@]}"
+
+echo ""
+echo "✔ All packages linked to local source."
+echo ""
+echo "⚠  Remember: 'npm install' wipes symlinks. Re-run 'npm run link' after installing packages."

package/scaffold/scripts/unlink.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# Unlink all @dfosco/* packages and restore registry versions.
+# Run from storyboard root: npm run unlink
+set -euo pipefail
+
+echo "Restoring @dfosco/* packages from registry..."
+npm install
+
+echo ""
+echo "✔ All packages restored to registry versions."

package/scaffold/skills/agent-browser/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: agent-browser
+description: Browser inspection and interaction during development using agent-browser CLI. Use when asked to inspect the browser, check the page, take a screenshot, get the accessibility tree, check for console errors, inspect an element, or see what's on screen.
+---
+
+# Agent Browser
+
+> Triggered by: "inspect the browser", "check the page", "what does the page look like", "browser snapshot", "screenshot the page", "get the accessibility tree", "check for console errors", "inspect element", "check the dev server", "what's on screen"
+
+Uses `agent-browser` to inspect and interact with the running dev server (or any URL) during development. Provides accessibility snapshots, screenshots, console error checking, element inspection, and interactive debugging — all without leaving the terminal.
+
+## Prerequisites
+
+```bash
+npm install -g agent-browser
+agent-browser install  # Downloads Chrome for Testing (first time only)
+```
+
+Both are already installed on this machine.
+
+## Core Workflow
+
+### Step 0: Resolve the target URL
+
+Before opening the browser, check for a saved `devURL` in the session database:
+
+```sql
+SELECT value FROM session_state WHERE key = 'devURL';
+```
+
+- **If the user provided a URL** (e.g. "inspect http://localhost:3000") — assume the dev server is already running at that URL. Use it directly and save it as `devURL` for the session. Do **not** start a dev server.
+  ```sql
+  INSERT OR REPLACE INTO session_state (key, value) VALUES ('devURL', 'http://localhost:3000');
+  ```
+- **If set** — use the saved `devURL`. Assume the dev server is already running.
+- **If neither** — fall back to `http://localhost:1234` and save it as `devURL`.
+
+### Step 1: Open the dev server
+
+Open the resolved URL in a headless browser session:
+
+```bash
+agent-browser --session dev open <devURL>
+```
+
+> **Headed mode:** If the user wants to see the browser window, add `--headed`:
+> ```bash
+> agent-browser --session dev --headed open <devURL>
+> ```
+
+> **Navigate to a specific prototype:** Append the prototype path:
+> ```bash
+> agent-browser --session dev open <devURL>/src/prototypes/Example
+> ```
+
+### Step 2: Inspect the page
+
+Choose the right inspection method based on what you need:
+
+#### Accessibility snapshot (best for understanding page structure)
+
+```bash
+agent-browser --session dev snapshot
+```
+
+Options:
+- `-i` — Interactive elements only (buttons, inputs, links)
+- `-c` — Compact (remove empty structural elements)
+- `-d 3` — Limit tree depth
+- `-s "#main"` — Scope to a CSS selector
+
+```bash
+# Common: interactive elements in the main content area
+agent-browser --session dev snapshot -i -c -s "main"
+```
+
+#### Screenshot
+
+```bash
+agent-browser --session dev screenshot /tmp/storyboard-screenshot.png
+```
+
+Options:
+- `--full` — Full page screenshot (not just viewport)
+- `--annotate` — Overlay numbered labels on interactive elements
+
+```bash
+# Annotated screenshot showing all interactive elements
+agent-browser --session dev screenshot --annotate /tmp/storyboard-annotated.png
+```
+
+#### Console errors
+
+```bash
+agent-browser --session dev console
+agent-browser --session dev errors
+```
+
+#### Get element info
+
+```bash
+agent-browser --session dev get text @e1      # Text content by ref
+agent-browser --session dev get html "#main"  # innerHTML by selector
+agent-browser --session dev get title         # Page title
+agent-browser --session dev get url           # Current URL
+```
+
+#### Check element state
+
+```bash
+agent-browser --session dev is visible "#my-element"
+agent-browser --session dev is enabled "#submit-btn"
+```
+
+### Step 3: Interact with the page
+
+After taking a snapshot, use refs (`@e1`, `@e2`, etc.) to interact:
+
+```bash
+agent-browser --session dev click @e2
+agent-browser --session dev fill @e3 "search query"
+agent-browser --session dev hover @e4
+agent-browser --session dev scroll down 300
+```
+
+Or use CSS selectors:
+
+```bash
+agent-browser --session dev click "#sidebar-toggle"
+agent-browser --session dev fill "input[name=search]" "hello"
+```
+
+### Step 4: Navigate
+
+```bash
+agent-browser --session dev open <devURL>/other-page
+agent-browser --session dev back
+agent-browser --session dev forward
+agent-browser --session dev reload
+```
+
+### Step 5: Close the session
+
+```bash
+agent-browser --session dev close
+```
+
+---
+
+## Common Recipes
+
+### Quick page check after a code change
+
+```bash
+agent-browser --session dev open <devURL>
+agent-browser --session dev snapshot -i -c
+agent-browser --session dev errors
+agent-browser --session dev close
+```
+
+### Screenshot + accessibility audit
+
+```bash
+agent-browser --session dev open <devURL>/src/prototypes/Example
+agent-browser --session dev screenshot --annotate /tmp/audit.png
+agent-browser --session dev snapshot
+agent-browser --session dev close
+```
+
+### Debug a specific component
+
+```bash
+agent-browser --session dev open <devURL>/src/prototypes/Example
+agent-browser --session dev snapshot -s "[data-testid=my-component]"
+agent-browser --session dev get html "[data-testid=my-component]"
+agent-browser --session dev close
+```
+
+### Check for JavaScript errors
+
+```bash
+agent-browser --session dev open <devURL>
+agent-browser --session dev wait --load networkidle
+agent-browser --session dev errors
+agent-browser --session dev console
+agent-browser --session dev close
+```
+
+### Batch multiple commands
+
+```bash
+agent-browser --session dev batch \
+  "open <devURL>" \
+  "wait --load networkidle" \
+  "snapshot -i -c" \
+  "errors" \
+  "screenshot /tmp/check.png"
+```
+
+### Viewport emulation
+
+```bash
+agent-browser --session dev set viewport 375 812    # iPhone-sized
+agent-browser --session dev set device "iPhone 14"  # Device preset
+agent-browser --session dev screenshot /tmp/mobile.png
+```
+
+### Network request inspection
+
+```bash
+agent-browser --session dev network requests --type xhr,fetch
+agent-browser --session dev network requests --filter api
+agent-browser --session dev network requests --status 4xx
+```
+
+### Visual diff between two pages
+
+```bash
+agent-browser --session dev diff url <devURL>/page-a <devURL>/page-b --screenshot
+```
+
+---
+
+## Session Management
+
+- **Named sessions** (`--session dev`) keep browser state across commands. Always use `--session dev` for the development workflow.
+- **Reuse sessions:** Don't close and reopen — just navigate with `open` or `goto`.
+- **Multiple sessions:** Use different names if inspecting multiple things at once:
+  ```bash
+  agent-browser --session dev open <devURL>
+  agent-browser --session prod open https://production-url.com
+  ```
+- **List sessions:** `agent-browser session list`
+- **Close all:** `agent-browser close --all`
+
+## Selectors
+
+| Type | Example | Notes |
+|------|---------|-------|
+| Ref | `@e1` | From snapshot output. Deterministic, preferred. |
+| CSS | `"#id"`, `".class"` | Standard CSS selectors |
+| Text | `"text=Submit"` | Match by text content |
+| XPath | `"xpath=//button"` | XPath expressions |
+| Semantic | `find role button --name "Submit"` | ARIA role-based |
+
+> **Prefer refs** (`@e1`) after taking a snapshot — they're deterministic and fast.
+
+## Troubleshooting
+
+- **"No active session"** — Run `agent-browser --session dev open <url>` first
+- **Dev server not running** — Start with `npm run dev` before inspecting
+- **Stale refs** — Take a new `snapshot` after page changes; refs are from the last snapshot
+- **Browser stuck** — `agent-browser close --all` or `agent-browser --session dev close`
+- **Chrome not found** — Run `agent-browser install`
+
+## Repository Cleanup
+
+- Screenshot files in `/tmp/` are ephemeral — no cleanup needed
+- Session data lives in `~/.agent-browser/` — not in the repo
+- Add `agent-browser.json` to `.gitignore` if you create a project-level config