td-ai-tools 1.2.0 → 1.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "td-ai-tools",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Install agent skills and packs into your project",
   "type": "module",
   "scripts": {

package/skills/README.md

@@ -7,6 +7,8 @@
 - `browser-validation`: Before completing a task validate frontend or template changes in a real browser with the Playwright-CLI…
 - `cache-reset`: Clear and warm Laravel and Statamic caches (including Statamic Glide image caches) after content or template…
 - `car-ticket-generator`: Generate a ticket for the codex-auto-runner queue
+- `client-overview`: Generate a client-facing markdown report that summarizes all changes on the current branch against the…
+- `debugging-ios-webkit`: Debugs iOS Safari/Chrome-iOS rendering bugs — stale paints, viewport/browser-chrome clipping, mobile-only CSS…
 - `everhour-basecamp-estimates`: Bulk update Everhour task estimates from a Basecamp todo or todolist URL, then append bracketed hours to the…
 - `forge-cli`: Manage Laravel Forge servers, sites, and provisioned resources from the terminal with the Laravel Forge CLI,…
 - `horizon-component-migration`: Bundle Shopify Horizon components into a migration package for a different theme, including recursive…
@@ -16,6 +18,7 @@
 - `pull-request-statamic`: Generates GitHub pull request descriptions for Statamic and Laravel development by analyzing git diffs and…
 - `record-changes`: Update `docs/changes.md` by summarizing the current branch against the primary development branch.
 - `shopify-cli`: Shopify CLI workflows for theme development.
+- `shopify-lint`: Run Shopify CLI Theme Check with Theory Digital's bundled custom checks while reporting and failing only on offenses in files modified on the current Git branch.
 - `stylesheet-migration`: Migrate Shopify Liquid `{% stylesheet %}` blocks into theme CSS assets using bundled Python scripts.
 - `td-js-vanilla-rules`: Theory Digital vanilla JavaScript standards for Shopify theme work.
 - `td-review`: Run parallel code review agents on a PR (including TD theme compliance) and produce a synthesized findings…

package/skills/client-overview/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: client-overview
+version: 1.0.0
+description: Generate a client-facing markdown report that summarizes all changes on the current branch against the primary development branch for a non-technical audience, with accessibility changes explained through end-user experience, accessibility benchmark categories, and practical impact.
+---
+
+# Client Overview
+
+Generate a markdown report for a client or stakeholder audience. Cover all meaningful branch changes, but refer to the work as an update (client's will not understand the term branch). Give extra attention to accessibility-related changes by explaining what people experience when using the affected feature, as well as which WCAG guidelines the change addresses.
+
+## Workflow
+
+### 1. Collect Branch Context
+
+Run the bundled script first:
+
+```bash
+python3 .agents/skills/client-overview/scripts/branch_client_overview_context.py
+```
+
+If the user specifies another comparison branch, pass it explicitly:
+
+```bash
+python3 .agents/skills/client-overview/scripts/branch_client_overview_context.py --base release/x.y
+```
+
+Default output folder: `docs/`, if the repo does not have a docs folder use the root instead. Do not use or reference the changes.md file, as that is intended for internal technical users. 
+
+### 2. Inspect the Actual Changes
+
+Use the script output to identify changed files, then inspect relevant diffs and source files with `git diff` and targeted reads. Do not rely on branch names or file names alone.
+
+Prioritize:
+
+- User-facing behavior, layout, copy, navigation, forms, search, cart, checkout, account, and content changes
+- Accessibility-relevant markup, ARIA, labels, headings, landmarks, alt text, focus handling, keyboard behavior, validation, contrast, spacing, motion, responsive behavior, and interactive controls
+- CSS and JavaScript changes that affect visibility, focus, scroll behavior, modals, drawers, menus, accordions, sliders, media, filters, or dynamic content
+- CMS settings or schema changes that alter what site admins can configure for visitors
+
+Do not summarize the report file edit itself as branch work. If the branch includes tooling-only changes, include them only when they affect the non-technical reader's experience or confidence in the release.
+
+### 3. Translate Accessibility Changes
+
+For each accessibility-relevant change, write in terms of:
+
+- **Benchmark category:** Use plain category names such as keyboard access, screen reader clarity, focus visibility, form labels and errors, color contrast, reduced motion, responsive reflow, touch target usability, readable content, or predictable navigation. Add WCAG references only if the code clearly maps to them.
+- **User experience:** State what someone with a disability, temporary impairment, or assistive technology setup can now do, understand, avoid, or recover from.
+- **Affected journey:** Name the feature or page area in shopper terms, such as product options, search filters, cart drawer, checkout path, navigation menu, newsletter signup, or collection browsing.
+- **Before/after effect:** Describe the practical improvement without blaming previous work. Example: "Keyboard shoppers can now see which control is active while moving through the menu."
+
+Avoid implementation-heavy language in the main summary. Keep file paths, selectors, variables, and component names out of the file unless there is a clear edge case requiring them.
+
+### 4. Write the Report
+
+Example entry structure:
+
+```markdown
+## <short user-facing title>
+**Date:** YYYY-MM-DD
+
+### At a Glance
+- <plain-language summary of the update outcome>
+
+### What Changed for Users
+| Area | User-facing change | Why it matters |
+|------|--------------------|----------------|
+
+### Accessibility Experience
+| Benchmark category | Affected experience | User impact |
+|--------------------|---------------------|-------------|
+```
+
+Guidelines:
+
+- Title the entry by the experience improved, not the branch name.
+- Write for clients, support, QA, designers, and stakeholders who may not read code.
+- In the output file, refer to the branch as "this update" or "the update"; do not call it "the branch".
+- Do not refer to yourself, the agent, or the writing process in the output file. Avoid first-person process statements such as "I reviewed," "I checked," "this summary," or "this report."
+- Prefer "people using keyboard navigation" over "keyboard users" when the sentence is about lived experience.
+- Prefer "screen reader announces..." only when the code change truly affects accessible names, roles, states, landmarks, headings, or live regions.
+
+### 5. Verify Before Finishing
+
+Before wrapping up:
+
+- Re-read the new markdown entry in context.
+- Confirm every listed file or area appears in the branch diff.
+- Confirm the report describes observed code behavior, not intended behavior inferred from a branch name.
+- Confirm accessibility claims are tied to a benchmark category and an affected user experience.
+
+## Resource
+
+- `scripts/branch_client_overview_context.py`: Resolve the best available base branch and print branch file changes with accessibility inspection hints.

package/skills/client-overview/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Client Overview"
+  short_description: "Summarize branch changes for clients"
+  default_prompt: "Use $client-overview to compare this branch to main and write a client-facing accessibility-focused change summary."

package/skills/client-overview/scripts/branch_client_overview_context.py

@@ -0,0 +1,317 @@
+#!/usr/bin/env python3
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+
+
+DEFAULT_BASE_CANDIDATES = ("main", "origin/main", "master", "origin/master")
+
+ACCESSIBILITY_HINTS = (
+    (
+        "keyboard access and focus behavior",
+        (
+            "focus",
+            "tabindex",
+            "keydown",
+            "keyup",
+            "keypress",
+            "escape",
+            "drawer",
+            "modal",
+            "menu",
+            "accordion",
+            "slider",
+            "carousel",
+        ),
+    ),
+    (
+        "screen reader clarity and semantic structure",
+        (
+            "aria",
+            "role",
+            "label",
+            "heading",
+            "h1",
+            "h2",
+            "h3",
+            "landmark",
+            "sr-only",
+            "visually-hidden",
+            "alt",
+        ),
+    ),
+    (
+        "form labels, instructions, and error recovery",
+        (
+            "form",
+            "input",
+            "select",
+            "textarea",
+            "error",
+            "invalid",
+            "required",
+            "newsletter",
+            "contact",
+        ),
+    ),
+    (
+        "color contrast, readable content, and visual state",
+        (
+            "color",
+            "contrast",
+            "opacity",
+            "background",
+            "foreground",
+            "text",
+            "font",
+            "hover",
+            "active",
+        ),
+    ),
+    (
+        "responsive reflow, zoom, and touch target usability",
+        (
+            "mobile",
+            "responsive",
+            "breakpoint",
+            "media",
+            "width",
+            "height",
+            "spacing",
+            "padding",
+            "touch",
+        ),
+    ),
+    (
+        "motion, animation, and scroll comfort",
+        (
+            "motion",
+            "animation",
+            "transition",
+            "scroll",
+            "autoplay",
+            "video",
+            "prefers-reduced-motion",
+        ),
+    ),
+)
+
+
+def run_git(*args: str) -> str:
+    completed = subprocess.run(
+        ["git", *args],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return completed.stdout.strip()
+
+
+def ref_exists(ref: str) -> bool:
+    completed = subprocess.run(
+        ["git", "rev-parse", "--verify", f"{ref}^{{commit}}"],
+        capture_output=True,
+        text=True,
+    )
+    return completed.returncode == 0
+
+
+def resolve_base_ref(explicit_base: str | None) -> str:
+    if explicit_base:
+        if not ref_exists(explicit_base):
+            raise SystemExit(f"Base ref not found: {explicit_base}")
+        return explicit_base
+
+    for candidate in DEFAULT_BASE_CANDIDATES:
+        if ref_exists(candidate):
+            return candidate
+
+    searched = ", ".join(DEFAULT_BASE_CANDIDATES)
+    raise SystemExit(f"No base ref found. Tried: {searched}")
+
+
+def parse_name_status(output: str) -> list[dict[str, str]]:
+    files = []
+    for line in output.splitlines():
+        if not line:
+            continue
+        parts = line.split("\t")
+        status = parts[0]
+
+        if status.startswith("R") and len(parts) >= 3:
+            files.append(
+                {
+                    "status": status,
+                    "path": parts[2],
+                    "old_path": parts[1],
+                }
+            )
+            continue
+
+        path = parts[1] if len(parts) > 1 else ""
+        files.append({"status": status, "path": path, "old_path": ""})
+    return files
+
+
+def parse_numstat(output: str) -> dict[str, dict[str, str]]:
+    stats = {}
+    for line in output.splitlines():
+        if not line:
+            continue
+        parts = line.split("\t")
+        if len(parts) < 3:
+            continue
+        additions, deletions, path = parts[0], parts[1], parts[2]
+        stats[path] = {"additions": additions, "deletions": deletions}
+    return stats
+
+
+def resolve_stats(
+    numstat: dict[str, dict[str, str]], path: str, old_path: str
+) -> dict[str, str] | None:
+    stats = numstat.get(path)
+    if stats or not old_path:
+        return stats
+
+    path_dir = os.path.dirname(path)
+    old_dir = os.path.dirname(old_path)
+    path_name = os.path.basename(path)
+    old_name = os.path.basename(old_path)
+
+    for candidate_path, candidate_stats in numstat.items():
+        if old_path in candidate_path and path in candidate_path:
+            return candidate_stats
+        if (
+            path_dir == old_dir
+            and path_dir
+            and candidate_path.startswith(f"{path_dir}/")
+            and old_name in candidate_path
+            and path_name in candidate_path
+        ):
+            return candidate_stats
+
+    return None
+
+
+def accessibility_hints_for(path: str) -> list[str]:
+    path_lower = path.lower()
+    _, ext = os.path.splitext(path_lower)
+    hints = []
+
+    for label, keywords in ACCESSIBILITY_HINTS:
+        if any(keyword in path_lower for keyword in keywords):
+            hints.append(label)
+
+    if ext in {".css", ".scss", ".sass"}:
+        hints.extend(
+            [
+                "color contrast, readable content, and visual state",
+                "responsive reflow, zoom, and touch target usability",
+            ]
+        )
+    elif ext in {".js", ".ts", ".jsx", ".tsx"}:
+        hints.extend(
+            [
+                "keyboard access and focus behavior",
+                "motion, animation, and scroll comfort",
+            ]
+        )
+    elif ext in {".liquid", ".html", ".vue", ".svelte"}:
+        hints.extend(
+            [
+                "screen reader clarity and semantic structure",
+                "form labels, instructions, and error recovery",
+            ]
+        )
+
+    return sorted(set(hints))
+
+
+def build_context(base_ref: str) -> dict[str, object]:
+    current_branch = run_git("branch", "--show-current")
+    merge_base = run_git("merge-base", base_ref, "HEAD")
+    shortstat = run_git("diff", "--shortstat", merge_base, "HEAD")
+    name_status = parse_name_status(
+        run_git("diff", "--name-status", "--find-renames", merge_base, "HEAD")
+    )
+    numstat = parse_numstat(run_git("diff", "--numstat", "--find-renames", merge_base, "HEAD"))
+
+    for entry in name_status:
+        stats = resolve_stats(numstat, entry["path"], entry["old_path"])
+        entry["additions"] = stats["additions"] if stats else "?"
+        entry["deletions"] = stats["deletions"] if stats else "?"
+        path_for_hints = f"{entry['old_path']} {entry['path']}".strip()
+        entry["accessibility_hints"] = accessibility_hints_for(path_for_hints)
+
+    return {
+        "current_branch": current_branch,
+        "base_ref": base_ref,
+        "merge_base": merge_base,
+        "shortstat": shortstat,
+        "files": name_status,
+    }
+
+
+def print_markdown(context: dict[str, object]) -> None:
+    print("# Branch Client Overview Context")
+    print()
+    print(f"- Current branch: `{context['current_branch']}`")
+    print(f"- Base ref: `{context['base_ref']}`")
+    print(f"- Merge base: `{context['merge_base']}`")
+    print(f"- Summary: {context['shortstat'] or 'No changes detected'}")
+    print()
+
+    files = context["files"]
+    if not files:
+        print("No changed files detected.")
+        return
+
+    print("| Status | Path | +/- | Accessibility inspection hints |")
+    print("|--------|------|-----|----------------------------------|")
+
+    for entry in files:
+        status = entry["status"]
+        path = entry["path"]
+        if entry["old_path"]:
+            path = f"{entry['old_path']} -> {entry['path']}"
+        delta = f"+{entry['additions']} / -{entry['deletions']}"
+        hints = ", ".join(entry["accessibility_hints"]) or "No obvious hint from file path"
+        print(f"| `{status}` | `{path}` | {delta} | {hints} |")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Resolve a base branch and print context for client-facing change reports."
+    )
+    parser.add_argument(
+        "--base",
+        help="Explicit base ref to compare against. Defaults to main/origin-main or master/origin-master fallback.",
+    )
+    parser.add_argument(
+        "--format",
+        choices=("markdown", "json"),
+        default="markdown",
+        help="Output format.",
+    )
+    args = parser.parse_args()
+
+    base_ref = resolve_base_ref(args.base)
+    context = build_context(base_ref)
+
+    if args.format == "json":
+        print(json.dumps(context, indent=2))
+    else:
+        print_markdown(context)
+
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except subprocess.CalledProcessError as error:
+        sys.stderr.write(error.stderr or str(error))
+        raise SystemExit(error.returncode)

package/skills/debugging-ios-webkit/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: debugging-ios-webkit
+description: Debugs iOS Safari/Chrome-iOS rendering bugs — stale paints, viewport/browser-chrome clipping, mobile-only CSS issues — in whichever environment is specified. Pass "playwright" (fast emulated WebKit), "simulator" (Xcode iOS Simulator via simctl), or "device" (USB-connected physical iPhone via pymobiledevice3 Web Inspector). Use when a bug is reported "only on iPhone", when the user wants to test on a real device or in the simulator, or when styles are correct but pixels are wrong.
+---
+
+# Debugging iOS WebKit Rendering Issues
+
+Every iOS browser is WebKit — "Safari and Chrome on iOS" is one engine.
+
+## Choose your environment
+
+Read ONLY the reference for the environment requested (or per the guidance
+below), then follow it:
+
+- **[references/playwright.md](references/playwright.md)** — emulated WebKit,
+  headless, seconds per iteration. CSS cascade, layout, load-order races,
+  scripted touch loops. Cannot reproduce iOS compositor/GPU or browser-chrome
+  behavior.
+- **[references/simulator.md](references/simulator.md)** — real iOS WebKit +
+  real Safari chrome via `simctl`. Viewport units (svh/dvh), safe-area,
+  pixel-accurate screenshots. No touch synthesis — drive state via URL params
+  or temporary page hooks.
+- **[references/device.md](references/device.md)** — physical iPhone over
+  USB. Attach to the live (broken) page, evaluate JS, capture render
+  snapshots, run stepped on-screen repair experiments with the person
+  watching. The whole truth; required for stale-compositor bugs.
+
+If the user didn't specify: start with playwright for speed, escalate to
+simulator when the bug involves viewport/chrome behavior, and to device when
+neither reproduces it or someone has the broken state on a phone right now.
+
+## Shared diagnostic: layout bug vs paint bug (read this regardless)
+
+In the broken state, measure **three** things: computed styles + bounding
+rects (JS), a render-tree snapshot (`Page.snapshotRect` on device, or a fresh
+screenshot in playwright/simulator), and what the eyes/screen actually show.
+
+- **Styles or rects wrong** → layout/cascade bug. Fix CSS. Iterate at the
+  playwright level.
+- **Styles, rects, AND snapshot correct while the screen shows garbage** →
+  the compositor is presenting a stale GPU texture. Fix with a paint
+  invalidation in JS, not with CSS. The cheapest reliable one is the opacity
+  nudge; to avoid a visible pop, dirty the layer *before* the element becomes
+  visible and keep nudging every animation frame through any entrance
+  transition:
+
+```js
+el.style.opacity = '0.99';
+const start = performance.now();
+(function tick() {
+  if (performance.now() - start < 350) {
+    el.style.opacity = el.style.opacity === '0.99' ? '1' : '0.99';
+    requestAnimationFrame(tick);
+  } else { el.style.opacity = ''; }
+})();
+```
+
+A painted background measuring exactly the element's *content-box* (instead
+of border-box) is the signature of unpainted padding — stale layer or native
+form-control painter (`-webkit-appearance` missing at first style pass).

package/skills/debugging-ios-webkit/references/device.md

@@ -0,0 +1,62 @@
+
+# Debugging on a Real iOS Device
+
+Attach to the live page over the cable — including a currently-broken state
+someone is looking at — without reloading or losing it.
+
+## Setup (once)
+
+```bash
+python3.12 -m venv venv && venv/bin/pip install pymobiledevice3
+```
+
+Python ≥ 3.10 required (Xcode's 3.9 breaks the CLI). On the phone:
+Settings → (Apps →) Safari → Advanced → **Web Inspector** ON. Plug in, trust.
+
+## Quick Start
+
+```bash
+venv/bin/python -m pymobiledevice3 webinspector opened-tabs      # list tabs
+python scripts/device_eval.py mystore.com '<js expression>'      # eval in tab
+python scripts/device_snapshot.py mystore.com out.png            # render snapshot
+python scripts/device_experiment.py mystore.com '.my-footer'     # live experiments
+```
+
+Scripts take a URL substring to pick the tab. First sanity check: confirm
+`location.href` and `Shopify.theme` — reporters are frequently on production
+or the wrong theme, which explains many "still happening" reports instantly.
+
+## Rules that prevent silent hangs
+
+- **One inspector client at a time.** Close Mac Safari's Develop-menu
+  inspector, or your attach hangs with no error.
+- The target tab must be **foreground** with the **screen unlocked**.
+- iOS 17+ wraps the protocol in the `Target` domain: sessions need
+  `wait_target=True` and responses arrive inside
+  `Target.dispatchMessageFromTarget` (the scripts handle both).
+- `ios_webkit_debug_proxy` lists tabs on modern iOS but its eval channel is
+  broken — use pymobiledevice3.
+
+## Applying the shared diagnostic here
+
+Run the layout-vs-paint diagnostic from SKILL.md using `device_eval.py`
+(rects + computed styles) and `device_snapshot.py` (render-tree snapshot,
+via `Page.snapshotRect` — it bypasses stale compositor layers, so a correct
+snapshot against a broken screen is the paint-bug proof).
+
+## Live repair experiments (stale-paint bugs)
+
+Don't guess which invalidation works — bisect it on the actual broken state
+with the reporter watching (`device_experiment.py`):
+
+1. A countdown banner tells them to reproduce the bug ("break it now,
+   steps start in 20s") — **warn them before starting so they're watching**.
+2. Numbered colored banners announce each repair candidate ~5s apart:
+   banner-only sanity → opacity nudge → `translateZ(0)` layer →
+   `display:none` rebuild → class re-toggle → scroll nudge.
+3. They report the step number that visually healed the element. Wire exactly
+   that operation into the code path that precedes the broken state.
+
+The winning invalidation (usually the opacity nudge — see the shared
+diagnostic in SKILL.md for the production-safe anti-pop version) goes into
+the code path that precedes the broken state.

package/skills/debugging-ios-webkit/references/playwright.md

@@ -0,0 +1,60 @@
+
+# Debugging with Playwright WebKit
+
+Every iOS browser is WebKit (Safari and Chrome-iOS share the engine), so
+Playwright's WebKit build catches most engine-level bugs in seconds, headless.
+
+## Quick Start
+
+```js
+const { webkit, devices } = require('playwright');
+const browser = await webkit.launch();
+const ctx = await browser.newContext({ ...devices['iPhone 14 Pro'], hasTouch: true });
+const page = await ctx.newPage();
+```
+
+One-off setup: `npm i playwright` in a scratch dir (e.g. `/tmp/repro`).
+
+## Instructions
+
+1. **Measure two ways, always.** Computed styles/rects via `page.evaluate`
+   AND painted pixels via `page.screenshot()` + a pixel scan. A paint bug
+   shows correct computed values with wrong pixels; if you only read
+   `getComputedStyle` you will wrongly conclude "works for me".
+
+2. **Real touch, not synthetic clicks.** Use `locator.tap()` (requires
+   `hasTouch: true`) when the bug involves touch-driven UI.
+
+3. **Interaction loops.** Before declaring something unreproducible, loop the
+   failing interaction 30x, measuring on every iteration:
+
+```js
+for (let i = 1; i <= 30; i++) {
+  await page.locator('.js-open-trigger').tap();   // your theme's selector
+  await page.waitForTimeout(400);
+  const m = await page.evaluate(() => {
+    const el = document.querySelector('#target-element');
+    const r = el.getBoundingClientRect();
+    return { w: Math.round(r.width), h: Math.round(r.height), pad: getComputedStyle(el).padding };
+  });
+  console.log(i, JSON.stringify(m));
+  await page.locator('.js-close-trigger').tap();
+  await page.waitForTimeout(300);
+}
+```
+
+4. **Slow-network CSS races.** Delay one stylesheet with `page.route()`.
+   Gotcha: a setup navigation warms the HTTP cache and the route never fires
+   on the test navigation — `route.abort()` the asset during setup, then
+   switch the handler to delay on the real run.
+
+5. **Test against the same origin the reporter used** (CDN preview vs local
+   proxy) — asset latency and compiled bundles differ per page and origin.
+
+## When this level is not enough
+
+Playwright WebKit renders everything from a healthy desktop compositor. If
+computed styles and screenshots are clean here but devices still show the bug,
+it lives in iOS-specific territory: dynamic viewport (`dvh`) lag, browser
+chrome show/hide, native form-control painters, or stale GPU textures.
+Escalate to references/simulator.md.