@alwaysmeticulous/debug-workspace 2.276.0 → 2.277.0

package/dist/screenshot-identifier.js

@@ -0,0 +1,51 @@
+"use strict";
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="705e4ec9-bebe-5a1f-a0c7-1ed6c389306f")}catch(e){}}();
+
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.screenshotIdentifierToBackendName = exports.screenshotIdentifierToFilename = exports.screenshotIdentifierToBaseName = void 0;
+/**
+ * Single source of truth for the on-disk screenshot basename (no extension)
+ * derived from a timeline/screenshot `identifier` object.
+ */
+const screenshotIdentifierToBaseName = (identifier) => {
+    const variantPortion = identifier.variant === "redacted" ? ".redacted" : "";
+    if (identifier.type === "end-state") {
+        return identifier.logicVersion == null
+            ? `final-state${variantPortion}`
+            : `final-state-v${identifier.logicVersion}${variantPortion}`;
+    }
+    if (identifier.type === "after-event" && identifier.eventNumber != null) {
+        const eventIndexStr = identifier.eventNumber.toString().padStart(5, "0");
+        return identifier.logicVersion == null
+            ? `screenshot-after-event-${eventIndexStr}${variantPortion}`
+            : `screenshot-after-event-${eventIndexStr}-v${identifier.logicVersion}${variantPortion}`;
+    }
+    return null;
+};
+exports.screenshotIdentifierToBaseName = screenshotIdentifierToBaseName;
+const screenshotIdentifierToFilename = (identifier) => {
+    const baseName = (0, exports.screenshotIdentifierToBaseName)(identifier);
+    return baseName == null ? undefined : `${baseName}.png`;
+};
+exports.screenshotIdentifierToFilename = screenshotIdentifierToFilename;
+/**
+ * Name accepted by the backend's replay-diff screenshot endpoints — differs
+ * from the on-disk basename: no zero-padding, no `logicVersion` suffix, and
+ * `end-state` instead of `final-state`. Returns `null` for redacted variants
+ * (backend naming unverified) and unknown types.
+ */
+const screenshotIdentifierToBackendName = (identifier) => {
+    if (identifier.variant === "redacted") {
+        return null;
+    }
+    if (identifier.type === "end-state") {
+        return "end-state";
+    }
+    if (identifier.type === "after-event" && identifier.eventNumber != null) {
+        return `after-event-${identifier.eventNumber}`;
+    }
+    return null;
+};
+exports.screenshotIdentifierToBackendName = screenshotIdentifierToBackendName;
+//# sourceMappingURL=screenshot-identifier.js.map
+//# debugId=705e4ec9-bebe-5a1f-a0c7-1ed6c389306f

package/dist/screenshot-identifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"screenshot-identifier.js","sources":["../src/screenshot-identifier.ts"],"sourceRoot":"","names":[],"mappings":";;;;;AAOA;;;GAGG;AACI,MAAM,8BAA8B,GAAG,CAC5C,UAAgC,EACjB,EAAE;IACjB,MAAM,cAAc,GAAG,UAAU,CAAC,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC;IAE5E,IAAI,UAAU,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QACpC,OAAO,UAAU,CAAC,YAAY,IAAI,IAAI;YACpC,CAAC,CAAC,cAAc,cAAc,EAAE;YAChC,CAAC,CAAC,gBAAgB,UAAU,CAAC,YAAY,GAAG,cAAc,EAAE,CAAC;IACjE,CAAC;IAED,IAAI,UAAU,CAAC,IAAI,KAAK,aAAa,IAAI,UAAU,CAAC,WAAW,IAAI,IAAI,EAAE,CAAC;QACxE,MAAM,aAAa,GAAG,UAAU,CAAC,WAAW,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QACzE,OAAO,UAAU,CAAC,YAAY,IAAI,IAAI;YACpC,CAAC,CAAC,0BAA0B,aAAa,GAAG,cAAc,EAAE;YAC5D,CAAC,CAAC,0BAA0B,aAAa,KAAK,UAAU,CAAC,YAAY,GAAG,cAAc,EAAE,CAAC;IAC7F,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AAnBW,QAAA,8BAA8B,kCAmBzC;AAEK,MAAM,8BAA8B,GAAG,CAC5C,UAAgC,EACZ,EAAE;IACtB,MAAM,QAAQ,GAAG,IAAA,sCAA8B,EAAC,UAAU,CAAC,CAAC;IAC5D,OAAO,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,QAAQ,MAAM,CAAC;AAC1D,CAAC,CAAC;AALW,QAAA,8BAA8B,kCAKzC;AAEF;;;;;GAKG;AACI,MAAM,iCAAiC,GAAG,CAC/C,UAAgC,EACjB,EAAE;IACjB,IAAI,UAAU,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;QACtC,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,UAAU,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QACpC,OAAO,WAAW,CAAC;IACrB,CAAC;IACD,IAAI,UAAU,CAAC,IAAI,KAAK,aAAa,IAAI,UAAU,CAAC,WAAW,IAAI,IAAI,EAAE,CAAC;QACxE,OAAO,eAAe,UAAU,CAAC,WAAW,EAAE,CAAC;IACjD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AAbW,QAAA,iCAAiC,qCAa5C","debugId":"705e4ec9-bebe-5a1f-a0c7-1ed6c389306f"}

package/dist/templates/CLAUDE.md

@@ -68,10 +68,18 @@ Each replay directory (`debug-data/replays/{head,base,other}/<replayId>/`) conta
 - `snapshotted-assets/` -- Static assets (JS/CSS) that were captured and used during replay.
   **Only present if `snapshotAssets` was enabled** -- check `launchBrowserAndReplayParams.json`
   for the `snapshotAssets` field before assuming this directory exists.
-
-Note: `screenshots/` are not copied into the workspace (they are large binary PNGs). Reference
-screenshot paths via `screenshotMap` in `context.json` instead; the actual files are in the
-replay cache at `~/.meticulous/replays/<replayId>/screenshots/`.
+- `screenshots/<name>.metadata.json` -- Per-screenshot metadata, including the captured `before.dom`
+  (full HTML at screenshot time) and, when an interaction followed, `after.dom`.
+- `screenshots/<name>.html` -- The `before.dom` extracted to a standalone HTML file. Prefer reading
+  this over grepping the metadata JSON. The one-line `<!-- screenshot=... url=... vt=... -->`
+  header at the top is for humans only and is not used when computing DOM diffs.
+- `screenshots/<name>.after.html` -- Same for `after.dom`, only present when the metadata
+  carried a non-null `after` side.
+
+Note: screenshot PNGs (the binary images themselves) are **not** copied into the workspace --
+only the `*.metadata.json` files that carry their DOM and the `.html` files extracted from
+them. Reference PNG paths via `screenshotMap` in `context.json`; the actual PNG files are in
+the replay cache at `~/.meticulous/replays/<replayId>/screenshots/`.
 
 Per-replay generated summaries:
 
@@ -98,9 +106,6 @@ Per-replay generated summaries:
   timeline: total entries, virtual time range, screenshot timestamps, event kind breakdown.
 - `debug-data/formatted-assets/<role>/<replayId>/` -- Pretty-printed JS/CSS from
   `snapshotted-assets/`. Only present if snapshotted assets exist. Use these instead of the originals.
-- `context.json` fields: `screenshotMap` (screenshot-to-timestamp mapping), `replayComparison`
-  (side-by-side event counts, virtual time, screenshot count), `fileMetadata` (byte sizes and
-  line counts for key files).
 
 ### Diff Files (only when comparing replays)
 
@@ -126,6 +131,26 @@ or `meticulous debug replay` with `--baseReplayId`.
 - `debug-data/screenshot-context/<id>.txt` -- Only generated with `--screenshot`. Shows ±30 lines
   of `logs.deterministic.txt` surrounding the screenshot for both head and base, with the
   screenshot line marked `>>>`.
+- `debug-data/dom-diffs/<headReplayId>-vs-<baseReplayId>-<screenshotBaseName>.diff` -- **Start
+  here for DOM changes.** Unified diff with 3 lines of context per hunk of the HEAD vs BASE
+  DOM at a specific screenshot, identical to the diff shown in the Meticulous product. Only
+  written when the DOMs actually differ.
+- `debug-data/dom-diffs/<headReplayId>-vs-<baseReplayId>-<screenshotBaseName>.full.diff` --
+  The same hunks as the sibling `.diff`, but with full-file context. Read this when 3 lines
+  of context around a hunk isn't enough to understand the surrounding DOM structure.
+- `debug-data/dom-diffs/<headReplayId>-vs-<baseReplayId>.summary.txt` -- Per-pair index of DOM
+  diffs: total screenshots compared, count breakdown by status, and a TSV table (`screenshot`,
+  `status`, `hunks`, `diff_bytes`, `url`).
+
+Note: DOM diffs are only generated when a `replayDiffId` is available (the normal
+`meticulous debug replay-diff <id>` path). On the rare `meticulous debug replay --baseReplayId`
+path there is no `replayDiffId`, so `dom-diffs/` is not generated — diff the per-replay
+`screenshots/<baseName>.html` files directly with the system `diff` command instead.
+
+Individual screenshots may also be marked `skipped-error` (backend fetch failed) or
+`skipped-unsupported` (e.g. redacted variants, or screenshots whose identifier couldn't
+be resolved from `timeline.json`) in the per-pair `.summary.txt`. For those, fall back
+to diffing the two `screenshots/<baseName>.html` files directly.
 
 ### Other Data
 
@@ -137,83 +162,90 @@ or `meticulous debug replay` with `--baseReplayId`.
   requests (HAR format), and application storage. Can be very large; prefer the session summary
   or use search to find relevant portions.
 - `debug-data/test-run/<testRunId>.json` -- Test run configuration, results, commit SHA, and status.
-- `debug-data/pr-metadata.json` -- Pull request metadata (title, URL, hosting provider, author, status) from
-  the database. May not be present if no PR is associated with the test run.
 - `debug-data/pr-diff.txt` -- Source code changes between the base and head commits. May not be present if
   commit SHAs are unavailable.
 - `debug-data/project-repo/` -- Your codebase checked out at the relevant commit. Only present if
   the command was run from within a git repository.
 
-## Screenshot Mapping
-
-`context.json` includes a `screenshotMap` that maps each screenshot to its virtual timestamp
-and event number. Use this to correlate screenshot filenames (e.g. `screenshot-after-event-00673.png`)
-with specific points in the replay timeline and logs.
-
-## Replay Comparison
-
-`context.json` includes a `replayComparison` array with side-by-side stats for each replay:
-total events, network requests, animation frames, virtual time, and screenshot count. Compare
-head vs base entries to quickly spot drift (e.g. extra animation frames or different virtual time).
-
-## File Sizes
-
-`context.json` includes a `fileMetadata` array with the byte size and line count of key files.
-Check this before attempting to read large files -- use grep/search or read specific line ranges
-for files over ~5000 lines instead of reading them in full.
+## Key `context.json` fields
+
+- `screenshotMap` -- maps each screenshot filename to its virtual timestamp and event number.
+  Use this to correlate e.g. `screenshot-after-event-00673.png` with a timeline position.
+- `replayComparison` -- side-by-side per-replay stats (events, network requests, animation
+  frames, virtual time, screenshots). Scan for head-vs-base drift.
+- `domDiffMap` -- keyed by `"<headReplayId>-vs-<baseReplayId>/<screenshotBaseName>"`. Each
+  entry carries `diffPath` (3-line-context), `fullDiffPath` (full-file-context),
+  `totalHunks`, `bytes`, and `url`. Both paths are `null` when HEAD and BASE DOMs were
+  identical. `fullDiffPath` alone can also be `null` when the full-context fetch failed
+  while the canonical succeeded — in that case `diffPath` is non-null and still usable.
+  Screenshots that are only-in-one-side, `skipped-error`, or `skipped-unsupported` have
+  **no entry** in the map; consult the per-pair `.summary.txt` for the full list. Empty
+  on the `--baseReplayId` single-replay path.
+- `fileMetadata` -- byte sizes and line counts for key files. Check this before reading
+  anything large; for files over ~5000 lines prefer grep/search or ranged reads.
 
 ## Debugging Workflow
 
-1. **Start with `debug-data/context.json`** -- Read this file for all IDs, statuses, file paths,
-   `screenshotMap`, and `replayComparison`. If a `screenshot` field is present, this is the
-   specific screenshot the user wants to investigate. Use `screenshotMap` to find its
-   virtual timestamp and event number, then focus your analysis on events leading up to it.
-2. **Check replay comparison** -- Compare head vs base entries in `replayComparison` for
-   immediate drift signals (different event counts, animation frames, virtual time).
-3. **Analyze log diffs** -- For diffs: **delegate to the log-diff-analyzer subagent** which
-   reads the filtered diffs and summaries and returns a structured divergence report. Only
-   read `debug-data/log-diffs/*.filtered.diff` directly if you need to verify specific details
-   from the analyzer's report. For single replays (no diff): read `logs.deterministic.filtered.txt`
-   inside the replay directory. Fall back to the raw `logs.deterministic.txt` only if you
-   need unmodified output.
-4. **Read events index** -- Check `debug-data/events-index/` for a greppable, one-line-per-event
-   listing of the full timeline. Use grep to filter by kind, virtual time, or URL.
-   For a higher-level overview, check `debug-data/timeline-summaries/`.
-5. **Search log messages** -- Use `debug-data/logs-index/` for a greppable, one-line-per-entry
-   summary of `logs.ndjson`. Grep by source (`source=application`), type (`type=warn`),
-   keyword, or virtual time (`vt=1234`).
-6. **Check screenshot timeline context** -- Read `debug-data/screenshot-timeline-context/` for
-   the timeline events surrounding each screenshot (30 before, 10 after). The screenshot line
-   is marked with `>>>`.
-7. **Inspect screenshot diffs** -- Start with `debug-data/diffs/<id>.summary.json` for a compact view of
-   which screenshots differ and by how much. If a `debug-data/screenshot-context/` file exists, read it
-   for the log lines surrounding the screenshot in both head and base.
-   Only read the full `debug-data/diffs/<id>.json` if you need complete replay metadata.
-8. **Check network activity** -- Read `debug-data/network-log/` for a compact network request
-   log. Grep for specific endpoints, status codes, or domains.
-9. **Compare virtual time progression** -- Use `diff` on `debug-data/vt-progression/` files to
-   find where head and base replays diverge in virtual time.
-10. **Check replay parameters** -- Read `debug-data/params-diffs/` for pre-computed diffs. For single
-    replays, read `launchBrowserAndReplayParams.json` directly.
-11. **Check assets diffs** -- Read `debug-data/assets-diffs/` to see if the snapshotted JS/CSS chunks
-    differ between head and base.
-12. **Analyze session data** -- Start with `debug-data/session-summaries/` for a quick overview of the
-    session (URL history, user events, network stats). Only read the raw `debug-data/sessions/` data
-    if you need specific details like request/response bodies or exact event selectors.
-13. **Analyze the PR diff** -- **Delegate to the pr-analyzer subagent** which reads
-    `debug-data/pr-diff.txt` and the diff summaries, returning a structured correlation of
-    code changes to screenshot diffs. Only read the PR diff directly if you need to verify
-    specific details from the analyzer's report.
-14. **Trace through formatted assets** -- Use `debug-data/formatted-assets/` (pretty-printed JS/CSS)
-    instead of raw minified bundles when tracing code execution.
-15. **Review your code** -- If `project-repo/` is present, check it for the relevant changes.
-    For library source code, use `debug-data/formatted-assets/` which contains the bundled and
-    pretty-printed versions of third-party code.
-
-**Important**: Do NOT use Python one-liners to parse `timeline.json` or `logs.ndjson`. The derived
-files above (`events-index/`, `network-log/`, `vt-progression/`, `logs-index/`,
-`screenshot-timeline-context/`) are pre-computed and greppable. Use `timeline.ndjson` (NDJSON format,
-one JSON object per line) if you need to grep the raw timeline data.
+Don't work through this top-to-bottom -- pick the phases relevant to the question. Phase 1
+applies to every investigation; then pick phase 2 (comparing replays) or phase 3 (single
+replay), and drop into phase 4 only as needed.
+
+### 1. Orient
+
+1. **Read `debug-data/context.json`** for IDs, statuses, file paths, `screenshotMap`,
+   `replayComparison`, and `fileMetadata`. If a `screenshot` field is present, that's the
+   specific screenshot the user wants to investigate -- use `screenshotMap` to find its
+   virtual timestamp and focus analysis on events leading up to it.
+2. **Scan `replayComparison`** for head-vs-base drift signals (event counts, animation
+   frames, virtual time, screenshot count).
+
+### 2. Investigate a diff (head vs base)
+
+3. **Screenshot diffs** -- read `debug-data/diffs/<id>.summary.json` for which screenshots
+   changed and by how much. If `debug-data/screenshot-context/` is present, read it for the
+   log lines around each screenshot. Only open the full `diffs/<id>.json` for complete
+   replay metadata.
+4. **DOM diffs** -- for each changed screenshot, open the matching `.diff` under
+   `debug-data/dom-diffs/` (use `domDiffMap` to navigate). If 3 lines of context around a
+   hunk isn't enough, open the sibling `.full.diff` file (same hunks with full-file context,
+   path on `domDiffMap[...].fullDiffPath`).
+5. **Log diffs** -- **delegate to the log-diff-analyzer subagent** instead of reading
+   `debug-data/log-diffs/*.filtered.diff` directly; only open the raw diff to verify
+   specific findings.
+6. **PR diff** -- **delegate to the pr-analyzer subagent** to correlate code changes with
+   visual diffs. Only open `debug-data/pr-diff.txt` directly to verify findings.
+
+### 3. Investigate a single replay
+
+7. **Filtered logs** -- read `logs.deterministic.filtered.txt` inside the replay directory.
+   Fall back to the raw `logs.deterministic.txt` only if you need unmodified output.
+8. **Events index** -- grep `debug-data/events-index/<role>-<replayId>.txt` by kind,
+   virtual time, or URL (e.g. `grep 'kind=screenshot'`, `grep 'api/v9/users'`). Prefer this
+   over parsing `timeline.json`.
+9. **Logs index** -- grep `debug-data/logs-index/<role>-<replayId>.txt` by source
+   (`source=application`), type (`type=warn`), keyword, or virtual time (`vt=1234`).
+
+### 4. Deeper dives (as needed)
+
+10. **Screenshot timeline context** -- `debug-data/screenshot-timeline-context/` for the 30
+    events before and 10 after each screenshot.
+11. **Network activity** -- grep `debug-data/network-log/` for endpoints, status codes,
+    domains.
+12. **Virtual time progression** -- `diff` on `debug-data/vt-progression/` files to find
+    where head and base diverge.
+13. **Replay parameters** -- `debug-data/params-diffs/` for computed diffs, or
+    `launchBrowserAndReplayParams.json` for a single replay.
+14. **Assets** -- `debug-data/assets-diffs/` for snapshotted JS/CSS diffs,
+    `debug-data/formatted-assets/` for pretty-printed bundles.
+15. **Session data** -- `debug-data/session-summaries/<sessionId>.txt` first; only read raw
+    `sessions/<id>/data.json` for specific request bodies or event selectors.
+16. **Project source** -- `project-repo/` when present; `formatted-assets/` for third-party
+    library code.
+
+**Important**: Do NOT use Python one-liners to parse `timeline.json` or `logs.ndjson`. The
+derived files above (`events-index/`, `logs-index/`, `network-log/`, `vt-progression/`,
+`screenshot-timeline-context/`) are pre-computed and greppable. Use `timeline.ndjson`
+(NDJSON format, one JSON object per line) if you need to grep the raw timeline data.
 
 ## Subagents
 
@@ -263,6 +295,11 @@ on expected vs unexpected changes.
   since real-time timestamps are stripped.
 - Session data files can be very large. Use grep/search to find relevant portions rather than
   reading entire files.
-- Screenshot images are binary PNG files stored in the replay cache (not in this workspace).
-  Reference them by path but analyze the diff metadata in JSON files instead.
+- Screenshot PNGs (the binary images) are stored in the replay cache (not in this workspace).
+  Reference them by path; for DOM content prefer reading
+  `debug-data/replays/<role>/<replayId>/screenshots/<name>.html` (or `.after.html`) rather than
+  parsing the raw `<name>.metadata.json`.
+- For DOM changes between replays, prefer `debug-data/dom-diffs/` over diffing the two
+  `<name>.html` files yourself -- the pre-computed `.diff` is identical to the diff shown
+  in the Meticulous product and already has context lines added.
 - Check `fileMetadata` in `context.json` for file sizes before reading large files.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alwaysmeticulous/debug-workspace",
-  "version": "2.276.0",
+  "version": "2.277.0",
   "description": "Shared debug workspace pipeline for investigating Meticulous diffs and replays",
   "license": "ISC",
   "main": "dist/index.js",
@@ -21,9 +21,9 @@
     "test": "vitest run --passWithNoTests"
   },
   "dependencies": {
-    "@alwaysmeticulous/client": "2.275.0",
-    "@alwaysmeticulous/common": "2.275.0",
-    "@alwaysmeticulous/downloading-helpers": "2.276.0",
+    "@alwaysmeticulous/client": "2.277.0",
+    "@alwaysmeticulous/common": "2.277.0",
+    "@alwaysmeticulous/downloading-helpers": "2.277.0",
     "chalk": "^4.1.2",
     "p-limit": "^3.1.0"
   },
@@ -36,7 +36,7 @@
     "url": "https://meticulous.ai"
   },
   "engines": {
-    "node": ">= 12"
+    "node": ">= 18"
   },
   "homepage": "https://github.com/alwaysmeticulous/meticulous-sdk",
   "repository": {
@@ -47,5 +47,5 @@
   "bugs": {
     "url": "https://github.com/alwaysmeticulous/meticulous-sdk/issues"
   },
-  "gitHead": "0498bc710e0b8273119f2ff7f1449d1f1e445506"
+  "gitHead": "655c31cccaab8ad5c213bdee56ae25479e589ed9"
 }