@inizioevoke/veeva-astroclm-core 1.1.1 → 1.1.2

package/agents/claude/analytics-auditor/SKILL.md

@@ -12,8 +12,8 @@ description: >
 ## Purpose
 
 Start the dev server, click interactive elements, harvest every `console.*` message,
-and produce a report of **unique messages** (grouped by page) written to
-`analytics-audit-report.md` in the project root.
+and produce a timestamped report of **unique messages** (grouped by page) written to
+`analytics-audit-report-<timestamp>.md` in the project root.
 
 ---
 
@@ -32,34 +32,61 @@ You will need all of those tools to be loaded and callable.
 
 ### Step 1 — Start the dev server and detect its port
 
-Astro auto-increments the port when the default (4321) is already in use, so never
-assume a fixed port. Instead, capture the server's own output to read the URL it
-actually binds to.
+Always start a fresh dev server. Use a timestamped log filename so the poll can never
+accidentally read the port from a previously running server's log:
 
-Run this command to start the server and tee its output to a temp file:
 ```bash
-npm run dev > /tmp/astro-dev.log 2>&1 &
+ASTRO_LOG="/tmp/astro-dev-$(date +%s).log"
+npm run dev > "$ASTRO_LOG" 2>&1 &
+echo "$ASTRO_LOG"
 ```
 
+Save the log path printed by the `echo` — you will need it for polling and cleanup.
+
 Then poll the log file until Astro prints its ready URL. **Do not use `grep -P`** —
 it is not supported on Windows. Use this portable polling loop instead:
+
 ```bash
-for i in $(seq 1 20); do
-  port=$(grep -o 'localhost:[0-9]*' /tmp/astro-dev.log | head -1 | grep -o '[0-9]*$')
-  if [ -n "$port" ]; then echo $port; break; fi
+port=""
+for i in $(seq 1 30); do
+  port=$(grep -o 'localhost:[0-9]*' "$ASTRO_LOG" | head -1 | grep -o '[0-9]*$')
+  if [ -n "$port" ]; then echo "$port"; break; fi
   sleep 1
 done
+if [ -z "$port" ]; then
+  echo "ERROR: dev server did not produce a port within 30 seconds" >&2
+  cat "$ASTRO_LOG" >&2
+  exit 1
+fi
 ```
 
+If the loop exits without a port, stop and report the error to the user — do not
+continue with subsequent steps.
+
 Extract the port from that output and use it as `DEV_PORT` for all subsequent URLs
 (e.g. `http://localhost:${DEV_PORT}/home/`).
 
-If the log file already contains a port before you start the server, the server was
-already running — use that port and skip the `npm run dev` step.
+Once the port has been extracted, delete the log file:
+```bash
+rm -f "$ASTRO_LOG"
+```
 
 ---
 
-### Step 2 — Discover pages and define click selectors
+### Step 2 — Capture timestamp, discover pages, and define click selectors
+
+#### Report timestamp
+
+Before starting any browser work, generate the timestamp that will be used in the
+report filename. Use `browser_evaluate` once the browser is open, or compute it via
+any available JS execution context:
+
+```js
+new Date().toISOString().replace(/[^\d]/g, '').substring(0, 14)
+```
+
+Store the result as **`TIMESTAMP`** (e.g. `20260616143022`). It is used once in Step 5
+to name the output file.
 
 #### Page URLs
 
@@ -69,7 +96,11 @@ all `.astro` files:
 find src/pages -name "*.astro" | sort
 ```
 
-Convert each file path to a URL route using these rules:
+**Skip any file whose name contains `[` or `]`** — these are dynamic route templates
+that require parameter values and cannot be visited directly. Record each skipped file
+in a list for the report's header section.
+
+Convert each remaining file path to a URL route using these rules:
 - Strip the `src/pages/` prefix and `.astro` extension
 - A file named `index.astro` maps to `/`
 - All other files map to `/<name>/` (trailing slash)
@@ -81,10 +112,35 @@ Example — `src/pages/home.astro` → `http://localhost:${DEV_PORT}/home/`
 
 #### Click selectors
 
-On every page, query for all elements matching the following selectors and click each
-one that is visible and not disabled:
+**Before finalizing the selector list, read `src/lib/client/main.ts`** (and any other
+files it imports from `src/lib/client/`) and check whether `IVA.configure()` or
+`IVA.init()` is called with a config object that contains any of these properties:
+
+- **`selectors.clickable`** — if present, it is a CSS selector string that replaces
+  the non-`[data-evotrk]` selectors in the default list. Replace those defaults with
+  this value, but **keep `[data-evotrk]`** (or the `attrs.data`-derived selector, see
+  below) in the final list.
+
+- **`attrs.data`** — if present, it is the attribute name used instead of
+  `data-evotrk` to mark tracked elements. It may or may not include surrounding
+  brackets. Normalize it: if it already starts with `[`, use it as-is; otherwise wrap
+  it as `[<value>]`. Replace `[data-evotrk]` in the selector list with this normalized
+  value.
+
+- **`attrs.navigateDisabled`** — if present, it is the attribute name IVA checks to
+  decide whether to skip its `navigate()` call. Store this value (without brackets)
+  as **`NAVIGATE_DISABLED_ATTR`** for use in Step 3. Default if absent:
+  `data-navigate-disabled`.
+
+- **`attrs.gotoslide`** — if present, it is the attribute name IVA uses to identify
+  which `<a>` elements it has bound its click handler to. Store this value (without
+  brackets) as **`GOTO_SLIDE_ATTR`** for use in Step 3. Default if absent:
+  `data-gotoslide`.
+
+If none of these properties are found, use this default list unchanged:
 
 ```
+[data-evotrk]
 a
 button
 [role="button"]
@@ -96,6 +152,9 @@ input[type="radio"]
 [role="radio"]
 ```
 
+On every page, query for all elements matching the final selector list and click each
+one that is visible and not disabled.
+
 Use a single combined CSS selector string joined with commas when querying the page.
 The user may supply additional or replacement selectors in their request — merge them
 into this list rather than replacing it entirely unless the user says otherwise.
@@ -104,25 +163,49 @@ into this list rather than replacing it entirely unless the user says otherwise.
 
 ### Step 3 — Per-page procedure
 
-For **each page URL** discovered in Step 2:
+For **each page URL** discovered in Step 2, also initialize a **`pageMessages`** list
+(reset to empty for each new page) that accumulates all console messages seen on the
+current page.
 
 1. Navigate to the page URL.
 2. Wait for the page to load (use `browser_wait_for` with a known selector like `h1`).
-3. **Inject a navigation guard** using `browser_evaluate` to prevent link clicks from
-   navigating away while still allowing the app's own click handlers (including
-   tracking) to run. Use a **bubble-phase** listener so the app's capture-phase and
-   bubble-phase handlers fire first:
+3. **Disable navigation on all links** using `browser_evaluate`. Pass
+   `NAVIGATE_DISABLED_ATTR` as the attribute name. This approach is reliable because
+   it works at the DOM level before any click handler fires:
+
+   - **IVA-bound links** — if the `<a>` element has the `GOTO_SLIDE_ATTR` attribute,
+     IVA has registered its click handler on it. Set `<NAVIGATE_DISABLED_ATTR>="true"`
+     on the element so IVA skips its `navigate()` call. IVA already calls
+     `e.preventDefault()` unconditionally, so browser default navigation is also
+     suppressed.
+
+   - **All other links** — if the `<a>` element does not have `GOTO_SLIDE_ATTR`
+     (external links, PDF links, plain anchors, etc.), remove the `href` attribute
+     entirely (store the original value in `data-original-href`). Without an `href`
+     the browser will not navigate; any IVA tracking handler still fires normally.
+
+   Use this script (substitute the actual attribute names for the placeholders):
    ```js
-   () => {
-     document.addEventListener('click', (e) => {
-       const a = e.target.closest('a');
-       if (a) e.preventDefault();
+   (gotoSlideAttr, navigateDisabledAttr) => {
+     document.querySelectorAll('a').forEach(a => {
+       if (a.hasAttribute(gotoSlideAttr)) {
+         // IVA-bound link — use IVA's own escape hatch
+         a.setAttribute(navigateDisabledAttr, 'true');
+       } else {
+         // Not IVA-bound — strip href to prevent browser navigation
+         const href = a.getAttribute('href');
+         if (href) {
+           a.dataset.originalHref = href;
+           a.removeAttribute('href');
+         }
+       }
      });
    }
    ```
-   This approach ensures tracking events fire before navigation is cancelled.
-   **Do NOT add a `beforeunload` listener** — it causes a "Leave site?" browser dialog
-   that blocks every subsequent Playwright navigation.
+
+   Call this evaluate **after** the page loads (Step 3.2) and **again after any
+   DOM mutation** (modal open, tab switch, dynamic content) that may have added new
+   `<a>` elements.
 
 4. Take a `browser_snapshot` to get the current accessibility tree. Use the refs from
    this snapshot for all subsequent clicks on this page.
@@ -130,17 +213,48 @@ For **each page URL** discovered in Step 2:
 5. For **each matched element** (visible, not disabled):
    a. Click it using `browser_click`.
    b. Wait 500ms for async effects.
-   c. If the click opened a modal or significantly changed the DOM, take a new
-      `browser_snapshot` before proceeding — snapshot refs become stale after DOM
-      changes and will cause errors if reused.
-   d. If a dialog appears (check the snapshot for `Modal state`), dismiss it with
-      `browser_handle_dialog` before continuing.
-
-6. After all clicks on the page, call `browser_console_messages` **once** with
-   `level: "debug"`. Since `all` defaults to `false`, this returns only the messages
-   from the current page navigation — no need to diff between clicks.
-
-7. Store all messages with the page route (e.g. `/home/`) as their source.
+   c. **Call `browser_console_messages` with `level: "debug"`** to get all messages
+      accumulated on this page so far. Identify the **newly appeared messages** by
+      comparing the full returned list against `pageMessages` (new = any message whose
+      de-timestamped text is not already present in `pageMessages`). Add all new
+      messages to `pageMessages`.
+   d. Take a `browser_snapshot`. If the tree is structurally unchanged from the
+      previous snapshot, the existing refs remain valid — no action needed. If the
+      tree changed, use the new snapshot's refs going forward.
+   e. If the snapshot shows a modal is now open (`Modal state` present in the tree):
+      i.   Use `browser_evaluate` to collect identifying information for all clickable
+           elements inside the modal:
+           ```js
+           () => {
+             const modal = document.querySelector('[role="dialog"], [aria-modal="true"]');
+             if (!modal) return [];
+             const sel = 'a,button,[role="button"],[role="link"],[role="tab"],input[type="checkbox"],input[type="radio"],[role="checkbox"],[role="radio"]';
+             return Array.from(modal.querySelectorAll(sel))
+               .filter(el => !el.disabled && el.offsetParent !== null)
+               .map(el => el.getAttribute('aria-label') || el.textContent.trim() || el.tagName);
+           }
+           ```
+           Cross-reference the returned labels/text against the current snapshot to
+           identify the corresponding accessibility-tree refs for clicking.
+      ii.  For each visible, non-disabled modal element: click it using its ref, wait
+           500ms, then apply the same **step 5c** above (call `browser_console_messages`
+           and diff). Re-snapshot if the modal content changes.
+      iii. After all modal elements have been clicked, dismiss the modal by clicking
+           its close button — look for a button with `aria-label="Close"` or visible
+           text "×", "Close", or "Dismiss" in the snapshot. Only use
+           `browser_handle_dialog` if a **native** browser dialog (`alert`/`confirm`/
+           `prompt`) is present — it has no effect on custom DOM modals.
+      iv.  Take a fresh `browser_snapshot` after the modal closes before continuing
+           to the next page-level element — refs from before the modal opened are stale.
+   f. If no modal appeared but the DOM changed significantly, use the new snapshot's
+      refs before proceeding.
+
+6. After all clicks on the page, call `browser_console_messages` **once more** with
+   `level: "debug"` to catch any async messages that fired after the last click. Diff
+   against `pageMessages` and append any remaining new messages.
+
+7. Store all messages in `pageMessages` with the page route (e.g. `/home/`) as their
+   source.
 
 ---
 
@@ -180,13 +294,30 @@ Gather every console message captured across all pages into a flat list:
 
 #### Deduplicate
 
-Two messages are duplicates if they share the same `text`. When the same message
-appears on multiple pages, record all pages it appeared on.
+Before comparing, **strip the leading timestamp prefix** from each message's `text`
+(the `[HH:MM:SS.mmm]` portion) — timestamps differ per run and would prevent identical
+messages from being recognized as duplicates. Compare only the de-timestamped text.
+
+Two messages are duplicates if their de-timestamped texts are equal. When the same
+message appears on multiple pages, record all pages it appeared on.
+
+#### Classify global vs. slide-specific tracking events
+
+After collecting all tracking events, split them into two groups. An event is **Global**
+if **either** condition is true:
+
+1. Its `type` starts with `header-`, `footer-`, or `nav-`; **or**
+2. The `(type, name)` pair appears on **≥ 80%** of the total audited pages.
+
+Everything else is a **Slide Event**.
+
+For global events, drop the `slide` dimension entirely — only `type` and `name` are needed.
+For slide events, retain `slide`, `type`, and `name`.
 
 #### Tiers
 
 Organize into four tiers:
-1. **Tracking Events** — messages matching the `DEBUG: track` pattern
+1. **Tracking Events** — messages matching the `DEBUG: track` pattern (split into Global and Slide sub-sections, see Step 5)
 2. **Errors** — `console.error`
 3. **Warnings** — `console.warn`
 4. **Info / Log** — `console.log`, `console.info`, `console.debug` (excluding tracking events)
@@ -195,22 +326,44 @@ Organize into four tiers:
 
 ### Step 5 — Write the report
 
-Write a Markdown file to `analytics-audit-report.md` in the project root with this structure:
+Before inserting any message text into a Markdown table cell, **escape every `|`
+character as `\|`** to prevent table corruption.
+
+Write a Markdown file to `analytics-audit-report-<TIMESTAMP>.md` in the project root with this
+structure:
 
 ```markdown
 # Browser Console Log Audit
 
 **Date:** <today's date>
 **Pages audited:** /home/, /about/, /about/moa/
-**Total unique messages:** <N>
+**Total unique messages:** <N> tracking events (<G> global, <S> slide-specific), <E> errors, <W> warnings, <I> info/log
+
+> **Skipped (dynamic routes):** src/pages/[slug].astro, src/pages/[...path].astro
 
 ---
 
 ## Tracking Events (<count>)
 
-| Slide | Type | Name | Pages |
-|-------|------|------|-------|
-| `home` | `button` | `button_evo_flip_card_trigger` | /home/ |
+> Events are grouped by slide. Each slide's `type` and `name` are set by the IVA tracking library at click time; the `slide` value is defined by each page's own configuration.
+
+### Global Events (<G> — type prefixed `header-`/`footer-`/`nav-`, or present on ≥80% of pages)
+
+These `(type, name)` pairs represent shared UI (navigation, ISI controls, header/footer
+links, etc.). The slide name is omitted since it is not meaningful here.
+
+| Type | Name |
+|------|------|
+| `nav-button` | `nav-button_about_pbc` |
+
+### Slide Events (<S> — page-specific)
+
+These events fire on fewer than 80% of pages and are meaningful to a specific slide or
+feature.
+
+| Slide | Type | Name |
+|-------|------|------|
+| `home` | `button` | `button_important_safety_information` |
 
 ## Errors (<count>)
 
@@ -235,10 +388,15 @@ Write a Markdown file to `analytics-audit-report.md` in the project root with th
 *Generated by the analytics-auditor skill.*
 ```
 
-If a tier has zero messages, write `_None_` instead of a table.
+Omit the "Skipped" blockquote if no dynamic routes were found. If a tier has zero
+messages, write `_None_` instead of a table. If there are no slide-specific events,
+write `_None_` under that sub-section. Omit the Global Events sub-section header note
+if there are no global events.
 
-After writing the file, tell the user where the report was saved and give a brief
-summary (e.g. "Found 8 tracking events, 2 errors, 1 warning, 5 info messages across 3 pages").
+After writing the file, tell the user the full filename (e.g.
+`analytics-audit-report-20260616143022.md`) and give a brief summary (e.g. "Found 8
+tracking events (5 global, 3 slide-specific), 2 errors, 1 warning, 5 info messages
+across 3 pages").
 
 ---
 
@@ -263,11 +421,20 @@ Do **not** stop the dev server — the user likely wants to keep it running.
 - **`grep -P` is not supported on Windows** — use `grep -o` with basic regex patterns.
 - **Snapshot refs go stale** after DOM mutations (modal open/close, tab switches). Always
   re-snapshot after any click that visibly changes the page structure.
-- **`browser_console_messages` fails if a dialog is showing** — check the snapshot for
-  `Modal state` and dismiss with `browser_handle_dialog` before calling it.
-- **Call `browser_console_messages` once per page** (at the end), not after every click.
-  The default `all: false` scopes results to the current navigation, giving a clean
-  per-page log with no diffing needed.
+- **`browser_console_messages` fails if a native dialog is showing** — dismiss with
+  `browser_handle_dialog` before calling it.
+- **`browser_handle_dialog` only works for native browser dialogs** (`alert`, `confirm`,
+  `prompt`) — it has no effect on custom DOM modals. Dismiss those by clicking their
+  close button.
+- **Navigation prevention uses DOM attributes, not event listeners.** IVA's click
+  handler calls `e.preventDefault()` unconditionally and then checks
+  `<navigateDisabledAttr>="true"` before calling `navigate()`. Setting that attribute
+  on IVA-bound links is therefore the most reliable way to suppress navigation without
+  interfering with tracking. All other links have their `href` removed instead.
+- **Re-run the link-disabling evaluate after DOM mutations** (modal open, dynamic
+  tab content, etc.) — newly inserted `<a>` elements will not have the attribute yet.
+- **`browser_console_messages` is called after every click** so that tracking events
+  are captured incrementally. The final per-page call catches any late async messages.
 - If the user provides their own list of selectors or pages, replace the defaults in
   Step 2 before proceeding.
 - If a selector does not match any element on a page, log a warning in the report's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inizioevoke/veeva-astroclm-core",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "",
   "license": "ISC",
   "author": "",