rhachet-roles-bhrowser 0.0.0

package/dist/domain.roles/playwright/briefs/debug/howto.debug-movie-frames.md

@@ -0,0 +1,182 @@
+# howto.debug-movie-frames
+
+## .what
+
+capture sequential snapshots at each step to create a "movie" of automation flow.
+
+## .why
+
+single snapshots show one moment. movie frames show:
+- state before each action
+- state after each action
+- where exactly flow diverged
+- what changed between steps
+
+essential for debug of multi-step flows.
+
+## .pattern
+
+```typescript
+/**
+ * .what = get movie identifier with timestamp fallback if null
+ * .why = isolates nullable coalesce + date logic from orchestrator
+ */
+const asMovieId = (input: { movieId: string | null }): string =>
+  input.movieId ?? String(Date.now());
+
+/**
+ * .what = capture movie frames at each step of automation flow
+ * .why = enables frame-by-frame debug of multi-step workflows
+ */
+export const action = async (
+  // movieId nullable: caller may not have identifier; defaults to timestamp
+  input: { email: string; password: string; movieId: string | null },
+  context: { page: Page; session: string },
+) => {
+  // determine snapshot directory via named transformer
+  const movieId = asMovieId({ movieId: input.movieId });
+  const snapshotDir = `.cache/browser.${context.session}/movie.${movieId}`;
+
+  const frame = async (input: { name: string }) => {
+    // capture state at this moment
+    await context.page.screenshot({ path: `${snapshotDir}/${input.name}.png` });
+    const html = await context.page.content();
+    await fs.writeFile(`${snapshotDir}/${input.name}.html`, html);
+    const url = context.page.url();
+    await fs.writeFile(`${snapshotDir}/${input.name}.url`, url);
+  };
+
+  // frame 0: initial state
+  await frame({ name: '00-initial' });
+
+  // action 1
+  await context.page.fill('#email', input.email);
+  await frame({ name: '01-email-filled' });
+
+  // action 2
+  await context.page.fill('#password', input.password);
+  await frame({ name: '02-password-filled' });
+
+  // action 3
+  await context.page.click('#submit');
+  await frame({ name: '03-submit-clicked' });
+
+  // wait for result
+  await context.page.waitForURL('**/dashboard');
+  await frame({ name: '04-dashboard-loaded' });
+};
+```
+
+## .output structure
+
+```
+.cache/browser.$SESSION/movie.$TIMESTAMP/
+├── 00-initial.png
+├── 00-initial.html
+├── 00-initial.url
+├── 01-email-filled.png
+├── 01-email-filled.html
+├── 01-email-filled.url
+├── 02-password-filled.png
+├── 02-password-filled.html
+├── 02-password-filled.url
+├── 03-submit-clicked.png
+├── 03-submit-clicked.html
+├── 03-submit-clicked.url
+├── 04-dashboard-loaded.png
+├── 04-dashboard-loaded.html
+└── 04-dashboard-loaded.url
+```
+
+## .debug workflow
+
+```
+flow failed at step 3
+  │
+  ├─> open 02-password-filled.png
+  │   └─ "password field filled correctly"
+  │
+  ├─> open 03-submit-clicked.png
+  │   └─ "error: submit button was disabled!"
+  │
+  └─> root cause: validation error not visible in 02
+      └─ check 02-password-filled.html for error message
+```
+
+## .frame helper
+
+```typescript
+/**
+ * .what = format frame number as zero-padded prefix
+ * .why = ensures consistent two-digit frame numbers for sort order
+ */
+const asFramePrefix = (input: { numFrame: number }): string =>
+  String(input.numFrame).padStart(2, '0');
+
+/**
+ * .what = persist single frame snapshot with explicit sequence number
+ * .why = pure function for frame capture; caller manages sequence
+ */
+const setFrameSnapshot = async (
+  input: { label: string; numFrame: number },
+  context: { page: Page; dir: string },
+): Promise<string> => {
+  // format frame name with sequence prefix
+  const prefix = asFramePrefix({ numFrame: input.numFrame });
+  const name = `${prefix}-${input.label}`;
+
+  // capture screenshot
+  await context.page.screenshot({ path: `${context.dir}/${name}.png`, fullPage: true });
+
+  // capture html content
+  await fs.writeFile(`${context.dir}/${name}.html`, await context.page.content());
+
+  // capture metadata
+  await fs.writeFile(`${context.dir}/${name}.meta.json`, JSON.stringify({
+    url: context.page.url(),
+    title: await context.page.title(),
+    time: new Date().toJSON(),
+  }, null, 2));
+
+  return name;
+};
+
+// usage in playbook
+/**
+ * .what = example playbook with frame capture at each step
+ * .why = demonstrates movie frame debug pattern in practice
+ */
+export const action = async (
+  // movieId nullable: caller may not have identifier; defaults to timestamp
+  input: { movieId: string | null },
+  context: { page: Page },
+) => {
+  // frame capture context via named transformer (immutable per frame)
+  const movieId = asMovieId({ movieId: input.movieId });
+  const frameContext = { page: context.page, dir: `.cache/movie.${movieId}` };
+
+  // capture frames with explicit sequence numbers
+  await setFrameSnapshot({ label: 'initial', numFrame: 0 }, frameContext);
+  await context.page.click('#start');
+  await setFrameSnapshot({ label: 'started', numFrame: 1 }, frameContext);
+  // ...
+};
+```
+
+## .comparison tools
+
+```bash
+# view frames in sequence
+ls -la .cache/browser.$SESSION/movie.*/
+
+# compare two frames
+diff 02-before.html 03-after.html
+
+# image diff (requires imagemagick)
+compare 02-before.png 03-after.png diff.png
+```
+
+## .see also
+
+- `howto.capture-state-on-error.md` — error state capture
+- `howto.browser-diagnosis.md` — diagnosis workflow

package/dist/domain.roles/playwright/briefs/diagnosis/howto.browser-diagnosis.md

@@ -0,0 +1,152 @@
+# howto.browser-diagnosis
+
+## .what
+
+systematic approach to diagnose browser automation issues.
+
+## .workflow
+
+```
+1. snapshot
+   └─> freeze state before it changes
+
+2. observe
+   ├─> screenshot: what's visible?
+   ├─> html: what's in dom?
+   ├─> console: any errors?
+   └─> network: requests failed?
+
+3. hypothesize
+   └─> form theory based on evidence
+
+4. test
+   └─> minimal action to test theory
+
+5. iterate
+   └─> new snapshot, new observation
+```
+
+## .step 1: snapshot
+
+```bash
+# capture all artifacts
+browser.snapshot --session $SESSION --focused
+
+# output location
+.cache/browser.$SESSION/snapshot.$TIMESTAMP/
+├── snapshot.meta.json
+├── snapshot.png
+├── snapshot.html
+├── snapshot.storage.json
+├── snapshot.console.json
+└── snapshot.network.json
+```
+
+## .step 2: observe
+
+### screenshot analysis
+
+```bash
+# view screenshot
+open .cache/browser.$SESSION/snapshot.*/snapshot.png
+
+# check:
+# - is the expected page visible?
+# - any overlays that block content?
+# - load indicators present?
+# - error messages displayed?
+```
+
+### html analysis
+
+```bash
+# search for element
+grep -i "submit" snapshot.html
+
+# check element visibility
+grep -B5 -A5 "submit" snapshot.html
+# look for: style="display:none", class="hidden", etc.
+```
+
+### console analysis
+
+```bash
+# check for errors
+cat snapshot.console.json | jq '.[] | select(.type == "error")'
+
+# common issues:
+# - uncaught TypeError (JS error)
+# - CORS errors (blocked requests)
+# - 404 (absent resources)
+```
+
+### network analysis
+
+```bash
+# check for failed requests
+cat snapshot.network.json | jq '.[] | select(.status >= 400)'
+
+# check for awaited requests
+cat snapshot.network.json | jq '.[] | select(.status == null)'
+```
+
+## .step 3: common diagnoses
+
+| symptom | likely cause | verification |
+|---------|--------------|--------------|
+| element not found | not in dom | grep html |
+| element not visible | CSS hidden | grep for display/visibility |
+| timeout | still loads | check network awaited |
+| wrong page | navigation issue | check screenshot url |
+| stale element | dom changed | re-snapshot |
+| click blocked | overlay present | screenshot shows modal |
+
+## .step 4: targeted action
+
+```bash
+# test hypothesis with minimal playbook
+browser.action --session $SESSION --play test-hypothesis.play.ts
+```
+
+```typescript
+// test-hypothesis.play.ts
+/**
+ * .what = test hypothesis about element visibility
+ * .why = validates theory with minimal action before complex fix
+ */
+export const action = async (
+  input: Record<string, never>,
+  context: { page: Page; log: LogMethods },
+) => {
+  // check element state
+  const element = await context.page.$('#my-element');
+  context.log.info('element exists:', { exists: !!element });
+  context.log.info('element visible:', { visible: await element?.isVisible() });
+};
+```
+
+## .step 5: iterate
+
+```bash
+# new snapshot after action
+browser.snapshot --session $SESSION --focused
+
+# compare to previous
+diff snapshot.before.html snapshot.after.html
+```
+
+## .diagnosis checklist
+
+- [ ] snapshot captured before debug?
+- [ ] screenshot reviewed?
+- [ ] html searched for target element?
+- [ ] console checked for errors?
+- [ ] network checked for failures?
+- [ ] hypothesis formed from evidence?
+- [ ] minimal test action executed?
+
+## .see also
+
+- `rule.require.snapshot-before-debug.md` — always snapshot first
+- `rule.require.grep-html-before-selector-guess.md` — search before select
+- `howto.debug-movie-frames.md` — capture action sequences

package/dist/domain.roles/playwright/briefs/diagnosis/rule.require.grep-html-before-selector-guess.md

@@ -0,0 +1,82 @@
+# rule.require.grep-html-before-selector-guess
+
+## .what
+
+search the html snapshot before you guess selectors.
+
+## .why
+
+guessed selectors fail because:
+- class names differ from what you expect
+- IDs are dynamically generated
+- structure changed since you last saw it
+- framework adds wrapper elements
+
+the html snapshot is the source of truth.
+
+## .pattern
+
+```bash
+# 1. capture snapshot
+browser.snapshot --session $SESSION --focused
+
+# 2. read the html
+cat .cache/browser.$SESSION/snapshot.*/snapshot.html
+
+# 3. search for your target
+grep -i "submit" .cache/browser.$SESSION/snapshot.*/snapshot.html
+grep -i "button" .cache/browser.$SESSION/snapshot.*/snapshot.html
+grep -i "login" .cache/browser.$SESSION/snapshot.*/snapshot.html
+```
+
+## .selector discovery
+
+| look for | grep pattern |
+|----------|--------------|
+| button text | `grep -i "sign in"` |
+| input placeholder | `grep -i "placeholder"` |
+| form action | `grep -i "action="` |
+| data attributes | `grep "data-test"` |
+| aria labels | `grep "aria-label"` |
+
+## .examples
+
+### good: search first
+
+```bash
+# find the login button
+grep -i "sign in\|login\|submit" snapshot.html
+# output: <button data-test="login-btn" class="xyz123">Sign In</button>
+
+# use the stable selector
+page.click('[data-test="login-btn"]')
+```
+
+### bad: guess selector
+
+```bash
+# 🚫 guess based on common patterns
+page.click('#login')  # not found
+page.click('.login-button')  # wrong class
+page.click('button[type="submit"]')  # multiple matches
+```
+
+## .selector preference order
+
+| priority | selector type | why |
+|----------|---------------|-----|
+| 1 | `data-test="..."` | stable, for test |
+| 2 | `aria-label="..."` | semantic, stable |
+| 3 | `[role="..."]` | semantic |
+| 4 | unique text | `text="Sign In"` |
+| 5 | id | may be dynamic |
+| 6 | class | often minified/dynamic |
+
+## .enforcement
+
+guessed selector without search of html = blocker
+
+## .see also
+
+- `rule.require.snapshot-before-assume.md` — snapshot first
+- `browser.snapshot html` — capture html

package/dist/domain.roles/playwright/briefs/diagnosis/rule.require.snapshot-before-assume.md

@@ -0,0 +1,73 @@
+# rule.require.snapshot-before-assume
+
+## .what
+
+take a snapshot before you assume page state. never guess what the browser shows.
+
+## .why
+
+assumptions about page state cause:
+- wrong selectors (element not visible)
+- wrong time (content not loaded)
+- wrong context (different page than expected)
+
+snapshots provide evidence for decisions.
+
+## .pattern
+
+```bash
+# before any assumption about state
+browser.snapshot --session $SESSION --focused
+
+# now you can see:
+# - screenshot: what's visible
+# - html: what's in dom
+# - console: any errors
+# - network: queued requests
+```
+
+## .antipattern
+
+```bash
+# 🚫 guess selector without view of page
+browser.action --session $SESSION --play click-submit.play.ts
+# fails: "element not found"
+# you: "but it should be there!"
+# reality: page shows login form, not submit button
+```
+
+## .examples
+
+### good: snapshot first
+
+```bash
+# see what's actually on page
+browser.snapshot --session $SESSION --focused
+# output: screenshot shows load spinner
+
+# now you know: wait for content
+browser.action --session $SESSION --play wait-for-content.play.ts
+```
+
+### bad: assume then debug
+
+```bash
+# assume page is ready
+browser.action --session $SESSION --play submit-form.play.ts
+# error: timeout awaited for #submit-button
+
+# now you snapshot to debug
+browser.snapshot --session $SESSION --focused
+# output: page shows captcha challenge
+
+# wasted time on wrong assumption
+```
+
+## .enforcement
+
+assumed page state without prior snapshot = blocker
+
+## .see also
+
+- `rule.require.snapshot-before-debug.md` — snapshot before debug
+- `rule.require.grep-html-before-selector-guess.md` — search before select

package/dist/domain.roles/playwright/briefs/diagnosis/rule.require.snapshot-before-debug.md

@@ -0,0 +1,81 @@
+# rule.require.snapshot-before-debug
+
+## .what
+
+before you debug any browser issue, capture a full snapshot.
+
+## .why
+
+debug without evidence is a guess:
+- symptoms change between observations
+- state mutates while you investigate
+- memory of what you saw is unreliable
+
+a snapshot freezes state for analysis.
+
+## .pattern
+
+```bash
+# action failed
+browser.action --session $SESSION --play failed-action.play.ts
+# error: could not find element
+
+# FIRST: capture state
+browser.snapshot --session $SESSION --focused
+
+# NOW: analyze frozen state
+# - screenshot: what user sees
+# - html: what dom contains
+# - console: error messages
+# - network: failed requests
+```
+
+## .what snapshots capture
+
+| artifact | reveals |
+|----------|---------|
+| screenshot | visual state, overlays, modals |
+| html | dom structure, hidden elements |
+| console | js errors, warnings, logs |
+| network | failed requests, awaited loads |
+| storage | cookies, localStorage state |
+| meta | url, title, tab info |
+
+## .diagnosis workflow
+
+```
+error occurs
+    │
+    └─> snapshot immediately
+          │
+          ├─> check screenshot
+          │   └─ visible state matches expectation?
+          │
+          ├─> check html
+          │   └─ element exists in dom?
+          │
+          ├─> check console
+          │   └─ js errors that prevent render?
+          │
+          └─> check network
+              └─ request failed or awaited?
+```
+
+## .antipattern
+
+```bash
+# 🚫 debug without snapshot
+# "let me check if the element exists..."
+browser.action --session $SESSION --play check-element.play.ts
+# "hmm, now it says different error..."
+# state has changed, you chase ghosts
+```
+
+## .enforcement
+
+debug browser issue without prior snapshot = blocker
+
+## .see also
+
+- `rule.require.snapshot-before-assume.md` — snapshot before assume
+- `howto.browser-diagnosis.md` — full diagnosis workflow

package/dist/domain.roles/playwright/briefs/diagnosis/rule.require.snapshot-latest-tab.md

@@ -0,0 +1,84 @@
+# rule.require.snapshot-latest-tab
+
+## .what
+
+when you diagnose issues, snapshot the latest (most recently opened) tab first.
+
+## .why
+
+- navigation often opens new tabs
+- popups and oauth flows spawn tabs
+- the action that failed likely happened in the newest tab
+- `--focused` gets the human-focused tab, but automation may be in another
+
+## .pattern
+
+```bash
+# first: see all tabs
+browser.describe --session $SESSION
+# output shows: tab 0 (original), tab 1 (oauth popup), tab 2 (result)
+
+# snapshot latest tab (highest index)
+browser.snapshot --session $SESSION --tab 2 --url 'expected-url.com'
+
+# if that's not the issue, work backwards
+browser.snapshot --session $SESSION --tab 1 --url 'oauth-provider.com'
+```
+
+## .tab order
+
+| index | typical content |
+|-------|-----------------|
+| 0 | original/start page |
+| 1 | first popup/redirect |
+| -1 | most recent (alias for highest) |
+
+## .common scenarios
+
+### oauth flow
+
+```
+user clicks "login with google"
+  │
+  ├─ tab 0: original site (awaited)
+  └─ tab 1: google oauth (active)
+       │
+       └─ tab 2: callback page (final result)
+```
+
+snapshot tab 2 first — that's where the result is.
+
+### file download
+
+```
+user clicks "download"
+  │
+  ├─ tab 0: original page
+  └─ tab 1: download initiated (may close)
+```
+
+### popup blocked
+
+```
+action opens popup
+  │
+  └─ tab 0: popup blocked notification
+       (no new tab created)
+```
+
+## .antipattern
+
+```bash
+# 🚫 always snapshot tab 0
+browser.snapshot --session $SESSION --tab 0
+# shows original page, but error is in popup tab
+```
+
+## .enforcement
+
+diagnose navigation issue without check of latest tab = blocker
+
+## .see also
+
+- `browser.describe.sh` — list all tabs
+- `rule.require.snapshot-before-debug.md` — snapshot first