td-ai-tools 1.2.0 → 1.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "td-ai-tools",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "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…

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.

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

@@ -0,0 +1,76 @@
+
+# Debugging in the iOS Simulator
+
+Real iOS WebKit + real Safari chrome, scriptable from the terminal. The one
+hard limitation: **you cannot synthesize taps** (`simctl` has no touch API,
+and macOS blocks synthetic clicks without Accessibility permission).
+
+## Quick Start
+
+```bash
+xcrun simctl list devices available            # find a device + UDID
+open -a Simulator --args -CurrentDeviceUDID <UDID>
+xcrun simctl bootstatus <UDID> -b              # wait for boot
+xcrun simctl openurl booted "https://site.example/page"
+xcrun simctl io booted screenshot /tmp/shot.png
+```
+
+## Driving state without touch
+
+- **URL parameters the page already supports** — e.g. many themes open the
+  cart drawer on load with `?cart=open`; check the theme's JS for what it reads.
+- **Temporary debug hooks** — add a query-param-gated script to the page that
+  auto-runs the interaction sequence, sync it to a dev theme, load with the
+  param, screenshot on a timer, then remove the hook:
+
+```js
+if (new URLSearchParams(location.search).has('debug_cycles')) {
+  window.addEventListener('load', async () => {
+    const t = (ms) => new Promise(r => setTimeout(r, ms));
+    // example: cycle whatever component is under test
+    const d = document.querySelector('cart-drawer');
+    await t(2000); d.open(); await t(2500); d.close(); await t(1500); d.open();
+  });
+}
+```
+
+- **App-switch nudge** (forces visibility/viewport recalc):
+  `xcrun simctl launch booted com.apple.Preferences; sleep 2; xcrun simctl launch booted com.apple.mobilesafari`
+
+## Measuring screenshots
+
+Screenshots are 3x scale on Pro-class devices — divide pixels by 3 for CSS px.
+Pixel-scan with PIL rather than eyeballing:
+
+```python
+from PIL import Image
+im = Image.open('/tmp/shot.png').convert('RGB')
+# find rows containing the element's known background colour, measure the band
+```
+
+Comparing the measured painted box against the element's expected border-box
+identifies which box was painted: a background at exactly content-box size
+means padding wasn't painted (stale layer or native form-control painter).
+
+## Calibrating viewport units
+
+The simulator reaches your Mac's `localhost` directly. Serve a test page
+(`python3 -m http.server 8899`) with fixed-position divs of `100svh`,
+`100dvh`, `100lvh`, `100%` height and a `bottom: 0` marker, screenshot, and
+measure where each ends. This settles "which viewport is this unit tracking"
+arguments with data.
+
+## Shopify-specific gotchas
+
+- Preview/development themes show the **Draft bar**, which overlays the
+  bottom ~46pt of the viewport and covers bottom-anchored CTAs — it looks
+  exactly like a layout bug. Append `&pb=0` to hide it before judging.
+- Add items to the cart with
+  `openurl booted ".../cart/add?id=<variant>&quantity=1&return_to=/cart"`
+  (a `/cart/<variant>:1` permalink jumps straight to checkout — not useful).
+
+## When this level is not enough
+
+If the bug needs real touch gestures, device GPU behavior, or you have the
+broken state live on someone's phone, use references/device.md. For fast CSS iteration first, use
+references/playwright.md.

package/skills/debugging-ios-webkit/scripts/device_eval.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+"""Evaluate JavaScript in a live Safari tab on a USB-connected iOS device.
+
+Usage:
+    python device_eval.py <url-substring> ['<js-expression>']
+
+The expression runs in the page and its return value is printed. Wrap DOM
+reads in an IIFE returning JSON.stringify(...) for structured output.
+Defaults to a generic element diagnostic if no expression is given.
+
+Requires: pip install pymobiledevice3 (Python >= 3.10)
+Phone: Settings -> Safari -> Advanced -> Web Inspector ON, tab foreground,
+screen unlocked, and no other inspector attached (close Mac Safari Develop).
+"""
+import asyncio
+import sys
+import uuid
+
+from pymobiledevice3.lockdown import create_using_usbmux
+from pymobiledevice3.services.webinspector import WebinspectorService
+from pymobiledevice3.services.web_protocol.inspector_session import InspectorSession
+from pymobiledevice3.services.web_protocol.session_protocol import SessionProtocol
+
+DEFAULT_EXPR = r"""(() => {
+  return JSON.stringify({
+    href: location.href.slice(0, 120),
+    theme: (window.Shopify && Shopify.theme) ? Shopify.theme : undefined,
+    vv: { h: Math.round(visualViewport.height), ih: innerHeight },
+  });
+})()"""
+
+
+async def attach(inspector, match):
+    pages = await inspector.get_open_application_pages(timeout=2)
+    ap = next((p for p in pages if match in (getattr(p.page, 'web_url', '') or '')), None)
+    if ap is None:
+        urls = [getattr(p.page, 'web_url', None) for p in pages]
+        raise SystemExit(f'no tab matching {match!r}; open tabs: {urls}')
+    session_id = str(uuid.uuid4()).upper()
+    # wait_target=True is required on iOS 17+ (Target-domain wrapped protocol)
+    session = await asyncio.wait_for(
+        InspectorSession.create(
+            SessionProtocol(inspector, session_id, ap.application, ap.page, method_prefix=""),
+            wait_target=True),
+        timeout=10)
+    await session.runtime_enable()
+    return session
+
+
+async def main():
+    match = sys.argv[1] if len(sys.argv) > 1 else 'http'
+    expr = sys.argv[2] if len(sys.argv) > 2 else DEFAULT_EXPR
+    lockdown = await create_using_usbmux()
+    inspector = WebinspectorService(lockdown=lockdown)
+    async with inspector:
+        session = await attach(inspector, match)
+        result = await asyncio.wait_for(session.runtime_evaluate(expr, return_by_value=True), timeout=15)
+        print(result)
+
+
+if __name__ == '__main__':
+    asyncio.run(main())

package/skills/debugging-ios-webkit/scripts/device_experiment.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""Run stepped repair experiments on a live broken page while a human watches
+the device. Each step is announced with a colored banner injected into the
+page; the watcher reports which step number visually fixed the element.
+
+Usage:
+    python device_experiment.py <url-substring> [target-css-selector]
+
+Edit STEPS for the element/bug at hand. The winning step becomes the
+permanent fix, wired into the code path that precedes the broken state.
+"""
+import asyncio
+import sys
+import uuid
+
+from pymobiledevice3.lockdown import create_using_usbmux
+from pymobiledevice3.services.webinspector import WebinspectorService
+from pymobiledevice3.services.web_protocol.inspector_session import InspectorSession
+from pymobiledevice3.services.web_protocol.session_protocol import SessionProtocol
+
+TARGET = sys.argv[2] if len(sys.argv) > 2 else 'body'
+
+STEPS = [
+    ("STEP 1: banner only (sanity)", "void 0"),
+    ("STEP 2: opacity nudge", f"""
+      (() => {{ const el = document.querySelector('{TARGET}'); if (!el) return;
+        el.style.opacity = '0.99';
+        requestAnimationFrame(() => {{ el.style.opacity = ''; }}); }})()"""),
+    ("STEP 3: own compositing layer", f"""
+      (() => {{ const el = document.querySelector('{TARGET}'); if (!el) return;
+        el.style.transform = 'translateZ(0)'; }})()"""),
+    ("STEP 4: display rebuild", f"""
+      (() => {{ const el = document.querySelector('{TARGET}'); if (!el) return;
+        el.style.display = 'none'; void el.offsetHeight; el.style.display = ''; }})()"""),
+    ("STEP 5: reflow via class re-toggle", f"""
+      (() => {{ const el = document.querySelector('{TARGET}'); if (!el) return;
+        const p = el.parentElement; p.classList.add('td-exp-retoggle');
+        void p.offsetHeight; p.classList.remove('td-exp-retoggle'); }})()"""),
+    ("STEP 6: scroll nudge", """
+      (() => { const s = document.scrollingElement; s.scrollTop += 1; s.scrollTop -= 1; })()"""),
+]
+
+BANNER = """
+(() => {
+  let el = document.getElementById('td-exp-banner');
+  if (!el) {
+    el = document.createElement('div');
+    el.id = 'td-exp-banner';
+    el.style.cssText = 'position:fixed;top:0;left:0;right:0;z-index:2147483647;padding:18px;font:bold 24px -apple-system;text-align:center;color:#fff;';
+    document.body.appendChild(el);
+  }
+  el.style.background = COLOR;
+  el.textContent = LABEL;
+})()
+"""
+
+COLORS = ['#c0392b', '#d35400', '#f39c12', '#27ae60', '#2980b9', '#8e44ad']
+
+
+async def main():
+    match = sys.argv[1] if len(sys.argv) > 1 else 'http'
+    lockdown = await create_using_usbmux()
+    inspector = WebinspectorService(lockdown=lockdown)
+    async with inspector:
+        pages = await inspector.get_open_application_pages(timeout=2)
+        ap = next((p for p in pages if match in (getattr(p.page, 'web_url', '') or '')), None)
+        if ap is None:
+            raise SystemExit(f'no tab matching {match!r}')
+        session_id = str(uuid.uuid4()).upper()
+        session = await asyncio.wait_for(
+            InspectorSession.create(
+                SessionProtocol(inspector, session_id, ap.application, ap.page, method_prefix=""),
+                wait_target=True),
+            timeout=10)
+        await session.runtime_enable()
+
+        async def banner(color, label):
+            await session.runtime_evaluate(BANNER.replace('COLOR', repr(color)).replace('LABEL', repr(label)))
+
+        # Lead-in so the watcher can reproduce the broken state first
+        for remaining in range(20, 0, -5):
+            await banner('#111', f'BREAK IT NOW — reproduce the bug. Steps start in {remaining}s')
+            print(f'lead-in {remaining}s', flush=True)
+            await asyncio.sleep(5)
+
+        for i, (label, code) in enumerate(STEPS):
+            await banner(COLORS[i % len(COLORS)], label + ' — fixed?')
+            await session.runtime_evaluate(code)
+            print('ran', label, flush=True)
+            await asyncio.sleep(5)
+
+        await banner('#111', 'DONE — report which step fixed it')
+        await asyncio.sleep(6)
+        await session.runtime_evaluate("document.getElementById('td-exp-banner')?.remove()")
+        print('done', flush=True)
+
+
+if __name__ == '__main__':
+    asyncio.run(main())

package/skills/debugging-ios-webkit/scripts/device_snapshot.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+"""Capture a Page.snapshotRect PNG from a live Safari tab on a USB device.
+
+Usage:
+    python device_snapshot.py <url-substring> [out.png] [x y w h]
+
+IMPORTANT: the snapshot repaints from the render tree. If the snapshot looks
+CORRECT while the device screen looks BROKEN, the bug is a stale compositor
+texture (paint bug), not a layout bug — fix with a paint invalidation (e.g.
+opacity nudge), not with CSS.
+"""
+import asyncio
+import base64
+import json
+import sys
+import uuid
+
+from pymobiledevice3.lockdown import create_using_usbmux
+from pymobiledevice3.services.webinspector import WebinspectorService
+from pymobiledevice3.services.web_protocol.inspector_session import InspectorSession
+from pymobiledevice3.services.web_protocol.session_protocol import SessionProtocol
+
+
+async def main():
+    match = sys.argv[1] if len(sys.argv) > 1 else 'http'
+    out = sys.argv[2] if len(sys.argv) > 2 else 'snapshot.png'
+    x, y, w, h = (int(a) for a in sys.argv[3:7]) if len(sys.argv) > 6 else (0, 0, 430, 932)
+
+    lockdown = await create_using_usbmux()
+    inspector = WebinspectorService(lockdown=lockdown)
+    async with inspector:
+        pages = await inspector.get_open_application_pages(timeout=2)
+        ap = next((p for p in pages if match in (getattr(p.page, 'web_url', '') or '')), None)
+        if ap is None:
+            raise SystemExit(f'no tab matching {match!r}')
+        session_id = str(uuid.uuid4()).upper()
+        session = await asyncio.wait_for(
+            InspectorSession.create(
+                SessionProtocol(inspector, session_id, ap.application, ap.page, method_prefix=""),
+                wait_target=True),
+            timeout=10)
+
+        mid = await session.send_message_to_target({'method': 'Page.enable', 'params': {}})
+        await asyncio.wait_for(session.receive_response_by_id(mid), timeout=10)
+
+        mid = await session.send_message_to_target(
+            {'method': 'Page.snapshotRect',
+             'params': {'x': x, 'y': y, 'width': w, 'height': h, 'coordinateSystem': 'Viewport'}})
+        res = await asyncio.wait_for(session.receive_response_by_id(mid), timeout=15)
+        # iOS 17+ wraps responses in the Target domain — unwrap
+        if res.get('method') == 'Target.dispatchMessageFromTarget':
+            res = json.loads(res['params']['message'])
+        data = res.get('result', res).get('dataURL', '')
+        if not data.startswith('data:image/png;base64,'):
+            raise SystemExit(f'snapshot failed: {json.dumps(res)[:200]}')
+        with open(out, 'wb') as f:
+            f.write(base64.b64decode(data.split(',', 1)[1]))
+        print('saved', out)
+
+
+if __name__ == '__main__':
+    asyncio.run(main())

package/skills/record-changes/SKILL.md

@@ -33,8 +33,8 @@ Use the script output to identify changed files, then inspect the relevant diffs
 Prioritize:
 
 - User-facing behavior changes
-- Theme setting/schema changes
-- CSS or markup changes that affect storefront rendering
+- CMS setting/schema changes
+- CSS or markup changes that affect rendering
 - Renamed files and vendor-theme hotspots
 
 Do not summarize the `docs/changes.md` edit itself as part of the branch work. If the branch contains unrelated skill or tooling files, either omit them from the changelog entry or separate them clearly when they are relevant to the project's maintenance history.
@@ -57,7 +57,7 @@ Guidelines:
 - Make the title describe the feature or fix, not the branch name.
 - Write `Purpose` in plain language with outcome-focused bullets.
 - Use the `Files changed` table to explain why each file matters.
-- Call out non-`td-` theme or vendor files in a separate subsection when they are upgrade-sensitive.
+- Call out non-`td-` theme or vendor files in a separate subsection when in a Shopify project.
 - Mention renamed files explicitly.
 - Keep `Upgrade impact` brief and concrete.
 - Use `Notes` for implementation details, edge cases, or assumptions.