From a6153e3cc687a085d878bb39db2d095c45988fa7 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Fri, 13 Mar 2026 15:52:39 -0700 Subject: [PATCH] fix: restore rich descriptions lost in auto-generation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Snapshot flags: add back value hints (-d , -s , -o ) - Snapshot flags: restore parenthetical context (@e refs, @c refs, etc.) - Commands: is → includes valid states enum - Commands: console → notes --errors filter behavior - Commands: press → lists common keys (Enter, Tab, Escape) - Commands: cookie-import-browser → describes picker UI - Commands: dialog-accept → specifies alert/confirm/prompt - Tips: restore → arrow (was downgraded to ->) --- SKILL.md | 28 ++++++++++++++-------------- SKILL.md.tmpl | 2 +- browse/SKILL.md | 26 +++++++++++++------------- browse/src/commands.ts | 12 ++++++------ browse/src/snapshot.ts | 15 ++++++++------- scripts/gen-skill-docs.ts | 6 ++---- 6 files changed, 44 insertions(+), 45 deletions(-) diff --git a/SKILL.md b/SKILL.md index 34d8c6b4..2f78a630 100644 --- a/SKILL.md +++ b/SKILL.md @@ -242,14 +242,14 @@ $B css ".button" "background-color" The snapshot is your primary tool for understanding and interacting with pages. ``` --i Interactive elements only --c Remove empty structural elements --d Limit tree depth --s Scope to CSS selector --D Diff against previous snapshot +-i Interactive elements only (buttons, links, inputs) with @e refs +-c Compact (no empty structural nodes) +-d Limit depth +-s Scope to CSS selector +-D Diff against previous snapshot (what changed?) -a Annotated screenshot with ref labels --o Output path for annotated screenshot --C Scan cursor:pointer/onclick/tabindex elements +-o Output path for screenshot +-C Cursor-interactive elements (@c refs — divs with pointer, onclick) ``` Combine flags: `$B snapshot -i -a -C -o /tmp/annotated.png` @@ -289,13 +289,13 @@ Refs are invalidated on navigation — run `snapshot` again after `goto`. | `click ` | Click element | | `cookie` | Set cookie | | `cookie-import ` | Import cookies from JSON file | -| `cookie-import-browser [browser] [--domain d]` | Import cookies from real browser | -| `dialog-accept [text]` | Auto-accept next dialog | +| `cookie-import-browser [browser] [--domain d]` | Import cookies from real browser (opens picker UI, or direct with --domain) | +| `dialog-accept [text]` | Auto-accept next alert/confirm/prompt | | `dialog-dismiss` | Auto-dismiss next dialog | | `fill ` | Fill input | | `header ` | Set custom request header | | `hover ` | Hover element | -| `press ` | Press key | +| `press ` | Press key (Enter, Tab, Escape, etc.) | | `scroll [sel]` | Scroll element into view | | `select ` | Select dropdown option | | `type ` | Type into focused element | @@ -307,13 +307,13 @@ Refs are invalidated on navigation — run `snapshot` again after `goto`. ### Inspection | Command | Description | |---------|-------------| -| `attrs ` | Element attributes as JSON | -| `console [--clear|--errors]` | Console messages | +| `attrs ` | Element attributes as JSON | +| `console [--clear|--errors]` | Console messages (--errors filters to error/warning) | | `cookies` | All cookies as JSON | | `css ` | Computed CSS value | | `dialog [--clear]` | Dialog messages | | `eval ` | Run JS file | -| `is ` | State check | +| `is ` | State check (visible/hidden/enabled/disabled/checked/editable/focused) | | `js ` | Run JavaScript | | `network [--clear]` | Network requests | | `perf` | Page load timings | @@ -356,7 +356,7 @@ Refs are invalidated on navigation — run `snapshot` again after `goto`. 1. **Navigate once, query many times.** `goto` loads the page; then `text`, `js`, `screenshot` all hit the loaded page instantly. 2. **Use `snapshot -i` first.** See all interactive elements, then click/fill by ref. No CSS selector guessing. -3. **Use `snapshot -D` to verify.** Baseline -> action -> diff. See exactly what changed. +3. **Use `snapshot -D` to verify.** Baseline → action → diff. See exactly what changed. 4. **Use `is` for assertions.** `is visible .modal` is faster and more reliable than parsing page text. 5. **Use `snapshot -a` for evidence.** Annotated screenshots are great for bug reports. 6. **Use `snapshot -C` for tricky UIs.** Finds clickable divs that the accessibility tree misses. diff --git a/SKILL.md.tmpl b/SKILL.md.tmpl index 5d6055c8..0ee150a7 100644 --- a/SKILL.md.tmpl +++ b/SKILL.md.tmpl @@ -237,7 +237,7 @@ $B css ".button" "background-color" 1. **Navigate once, query many times.** `goto` loads the page; then `text`, `js`, `screenshot` all hit the loaded page instantly. 2. **Use `snapshot -i` first.** See all interactive elements, then click/fill by ref. No CSS selector guessing. -3. **Use `snapshot -D` to verify.** Baseline -> action -> diff. See exactly what changed. +3. **Use `snapshot -D` to verify.** Baseline → action → diff. See exactly what changed. 4. **Use `is` for assertions.** `is visible .modal` is faster and more reliable than parsing page text. 5. **Use `snapshot -a` for evidence.** Annotated screenshots are great for bug reports. 6. **Use `snapshot -C` for tricky UIs.** Finds clickable divs that the accessibility tree misses. diff --git a/browse/SKILL.md b/browse/SKILL.md index 03088102..7b9a6cff 100644 --- a/browse/SKILL.md +++ b/browse/SKILL.md @@ -104,14 +104,14 @@ $B diff https://staging.app.com https://prod.app.com The snapshot is your primary tool for understanding and interacting with pages. ``` --i Interactive elements only --c Remove empty structural elements --d Limit tree depth --s Scope to CSS selector --D Diff against previous snapshot +-i Interactive elements only (buttons, links, inputs) with @e refs +-c Compact (no empty structural nodes) +-d Limit depth +-s Scope to CSS selector +-D Diff against previous snapshot (what changed?) -a Annotated screenshot with ref labels --o Output path for annotated screenshot --C Scan cursor:pointer/onclick/tabindex elements +-o Output path for screenshot +-C Cursor-interactive elements (@c refs — divs with pointer, onclick) ``` Combine flags: `$B snapshot -i -a -C -o /tmp/annotated.png` @@ -151,13 +151,13 @@ Refs are invalidated on navigation — run `snapshot` again after `goto`. | `click ` | Click element | | `cookie` | Set cookie | | `cookie-import ` | Import cookies from JSON file | -| `cookie-import-browser [browser] [--domain d]` | Import cookies from real browser | -| `dialog-accept [text]` | Auto-accept next dialog | +| `cookie-import-browser [browser] [--domain d]` | Import cookies from real browser (opens picker UI, or direct with --domain) | +| `dialog-accept [text]` | Auto-accept next alert/confirm/prompt | | `dialog-dismiss` | Auto-dismiss next dialog | | `fill ` | Fill input | | `header ` | Set custom request header | | `hover ` | Hover element | -| `press ` | Press key | +| `press ` | Press key (Enter, Tab, Escape, etc.) | | `scroll [sel]` | Scroll element into view | | `select ` | Select dropdown option | | `type ` | Type into focused element | @@ -169,13 +169,13 @@ Refs are invalidated on navigation — run `snapshot` again after `goto`. ### Inspection | Command | Description | |---------|-------------| -| `attrs ` | Element attributes as JSON | -| `console [--clear|--errors]` | Console messages | +| `attrs ` | Element attributes as JSON | +| `console [--clear|--errors]` | Console messages (--errors filters to error/warning) | | `cookies` | All cookies as JSON | | `css ` | Computed CSS value | | `dialog [--clear]` | Dialog messages | | `eval ` | Run JS file | -| `is ` | State check | +| `is ` | State check (visible/hidden/enabled/disabled/checked/editable/focused) | | `js ` | Run JavaScript | | `network [--clear]` | Network requests | | `perf` | Page load timings | diff --git a/browse/src/commands.ts b/browse/src/commands.ts index bdcf9586..c3189ace 100644 --- a/browse/src/commands.ts +++ b/browse/src/commands.ts @@ -51,9 +51,9 @@ export const COMMAND_DESCRIPTIONS: Record' }, 'eval': { category: 'Inspection', description: 'Run JS file', usage: 'eval ' }, 'css': { category: 'Inspection', description: 'Computed CSS value', usage: 'css ' }, - 'attrs': { category: 'Inspection', description: 'Element attributes as JSON', usage: 'attrs ' }, - 'is': { category: 'Inspection', description: 'State check', usage: 'is ' }, - 'console': { category: 'Inspection', description: 'Console messages', usage: 'console [--clear|--errors]' }, + 'attrs': { category: 'Inspection', description: 'Element attributes as JSON', usage: 'attrs ' }, + 'is': { category: 'Inspection', description: 'State check (visible/hidden/enabled/disabled/checked/editable/focused)', usage: 'is ' }, + 'console': { category: 'Inspection', description: 'Console messages (--errors filters to error/warning)', usage: 'console [--clear|--errors]' }, 'network': { category: 'Inspection', description: 'Network requests', usage: 'network [--clear]' }, 'dialog': { category: 'Inspection', description: 'Dialog messages', usage: 'dialog [--clear]' }, 'cookies': { category: 'Inspection', description: 'All cookies as JSON' }, @@ -65,17 +65,17 @@ export const COMMAND_DESCRIPTIONS: Record ' }, 'hover': { category: 'Interaction', description: 'Hover element', usage: 'hover ' }, 'type': { category: 'Interaction', description: 'Type into focused element', usage: 'type ' }, - 'press': { category: 'Interaction', description: 'Press key', usage: 'press ' }, + 'press': { category: 'Interaction', description: 'Press key (Enter, Tab, Escape, etc.)', usage: 'press ' }, 'scroll': { category: 'Interaction', description: 'Scroll element into view', usage: 'scroll [sel]' }, 'wait': { category: 'Interaction', description: 'Wait for element/condition', usage: 'wait ' }, 'upload': { category: 'Interaction', description: 'Upload file(s)', usage: 'upload ' }, 'viewport':{ category: 'Interaction', description: 'Set viewport size', usage: 'viewport ' }, 'cookie': { category: 'Interaction', description: 'Set cookie' }, 'cookie-import': { category: 'Interaction', description: 'Import cookies from JSON file', usage: 'cookie-import ' }, - 'cookie-import-browser': { category: 'Interaction', description: 'Import cookies from real browser', usage: 'cookie-import-browser [browser] [--domain d]' }, + 'cookie-import-browser': { category: 'Interaction', description: 'Import cookies from real browser (opens picker UI, or direct with --domain)', usage: 'cookie-import-browser [browser] [--domain d]' }, 'header': { category: 'Interaction', description: 'Set custom request header', usage: 'header ' }, 'useragent': { category: 'Interaction', description: 'Set user agent', usage: 'useragent ' }, - 'dialog-accept': { category: 'Interaction', description: 'Auto-accept next dialog', usage: 'dialog-accept [text]' }, + 'dialog-accept': { category: 'Interaction', description: 'Auto-accept next alert/confirm/prompt', usage: 'dialog-accept [text]' }, 'dialog-dismiss': { category: 'Interaction', description: 'Auto-dismiss next dialog' }, // Visual 'screenshot': { category: 'Visual', description: 'Save screenshot', usage: 'screenshot [path]' }, diff --git a/browse/src/snapshot.ts b/browse/src/snapshot.ts index 9fb63d47..d3a84b5e 100644 --- a/browse/src/snapshot.ts +++ b/browse/src/snapshot.ts @@ -52,16 +52,17 @@ export const SNAPSHOT_FLAGS: Array<{ long: string; description: string; takesValue?: boolean; + valueHint?: string; optionKey: keyof SnapshotOptions; }> = [ - { short: '-i', long: '--interactive', description: 'Interactive elements only', optionKey: 'interactive' }, - { short: '-c', long: '--compact', description: 'Remove empty structural elements', optionKey: 'compact' }, - { short: '-d', long: '--depth', description: 'Limit tree depth', takesValue: true, optionKey: 'depth' }, - { short: '-s', long: '--selector', description: 'Scope to CSS selector', takesValue: true, optionKey: 'selector' }, - { short: '-D', long: '--diff', description: 'Diff against previous snapshot', optionKey: 'diff' }, + { short: '-i', long: '--interactive', description: 'Interactive elements only (buttons, links, inputs) with @e refs', optionKey: 'interactive' }, + { short: '-c', long: '--compact', description: 'Compact (no empty structural nodes)', optionKey: 'compact' }, + { short: '-d', long: '--depth', description: 'Limit depth', takesValue: true, valueHint: '', optionKey: 'depth' }, + { short: '-s', long: '--selector', description: 'Scope to CSS selector', takesValue: true, valueHint: '', optionKey: 'selector' }, + { short: '-D', long: '--diff', description: 'Diff against previous snapshot (what changed?)', optionKey: 'diff' }, { short: '-a', long: '--annotate', description: 'Annotated screenshot with ref labels', optionKey: 'annotate' }, - { short: '-o', long: '--output', description: 'Output path for annotated screenshot', takesValue: true, optionKey: 'outputPath' }, - { short: '-C', long: '--cursor-interactive', description: 'Scan cursor:pointer/onclick/tabindex elements', optionKey: 'cursorInteractive' }, + { short: '-o', long: '--output', description: 'Output path for screenshot', takesValue: true, valueHint: '', optionKey: 'outputPath' }, + { short: '-C', long: '--cursor-interactive', description: 'Cursor-interactive elements (@c refs — divs with pointer, onclick)', optionKey: 'cursorInteractive' }, ]; interface ParsedNode { diff --git a/scripts/gen-skill-docs.ts b/scripts/gen-skill-docs.ts index 63af19bb..19b68000 100644 --- a/scripts/gen-skill-docs.ts +++ b/scripts/gen-skill-docs.ts @@ -63,10 +63,8 @@ function generateSnapshotFlags(): string { ]; for (const flag of SNAPSHOT_FLAGS) { - const flagStr = flag.takesValue - ? `${flag.short.padEnd(10)}${flag.description}` - : `${flag.short.padEnd(10)}${flag.description}`; - lines.push(flagStr); + const label = flag.valueHint ? `${flag.short} ${flag.valueHint}` : flag.short; + lines.push(`${label.padEnd(10)}${flag.description}`); } lines.push('```');