**4 issues found** across 6 files Confidence score: **3/5** - There is a concrete behavior bug in `packages/core/lib/v3/understudy/a11y/snapshot/capture.ts` where `hashMode` isn’t passed in the scoped snapshot path, so `treeOnly` + `focusSelector` can yield inconsistent formatting. - Public API surface is being expanded via exports from `packages/core/lib/v3/index.ts`, which pulls in internal types from `types/private/snapshot.ts` and may lock in implementation details. - Given the above, there’s some regression risk if downstream users rely on the scoped snapshot or if future refactors need to change internal types. - Pay close attention to `packages/core/lib/v3/understudy/a11y/snapshot/capture.ts` and `packages/core/lib/v3/index.ts` - scoped snapshot formatting and public API exposure of internal types.

Prompt for AI agents (unresolved issues)

```text Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately. P2: According to linked Linear issue STG-1250, `captureHybridSnapshot` is being shared between the API and SDK internally. The codebase convention for internal cross-package exports is to prefix with `__internal` (e.g., `__internalCreateInMemoryAgentCacheHandle`). Consider renaming: ```ts export { captureHybridSnapshot as __internalCaptureHybridSnapshot } from "./understudy/a11y/snapshot/index.js"; ``` This signals to consumers that this is not a stable public API. P2: These types are sourced from `types/private/snapshot.ts`, yet they're being exported from the package's public entry point. This turns internal implementation types into a public API contract, reducing refactoring flexibility. If these types need to be shared across the API and SDK, consider either moving them to a public types module or creating a shared internal package — rather than promoting private types to the public surface. (Based on your team's feedback about avoiding exposing internal types as public APIs.) [FEEDBACK_USED] P2: `SnapshotOptions` is re-exported publicly from `packages/core/lib/v3/index.ts`. Adding `treeOnly` here locks it into the public API contract. Since this option is described as serving internal callers ("DOM hashing, cache keys"), consider whether it belongs on the public type or should live on a separate internal-only options type to avoid committing to this shape before there's real user signal. (Based on your team's feedback about stabilizing APIs before exposing parameters publicly and avoiding exposing internal types as public APIs.) [FEEDBACK_USED] P1: Bug: `hashMode` is not passed to `a11yForFrame` in the scoped snapshot path (`tryScopedSnapshot`), so when `treeOnly: true` and a `focusSelector` successfully scopes the snapshot, the tree will use standard formatting (`formatTreeLine`) instead of hash-friendly formatting (`formatTreeLineForHash`). This makes the output inconsistent depending on which code path is taken. `tryScopedSnapshot` needs to propagate `hashMode` (or `treeOnly`) into its `a11yForFrame` call to match the behavior added in `collectPerFrameMaps`. ```

Architecture diagram

```mermaid sequenceDiagram participant Caller as SDK / API Route participant Snap as Snapshot Manager (captureHybridSnapshot) participant Frame as Frame Processor (a11yForFrame) participant Fmt as Tree Formatter (treeFormatUtils) participant CDP as Browser (CDP) Note over Caller,CDP: NEW: Unified Deterministic Snapshot Flow (STG-1250) Caller->>Snap: captureHybridSnapshot(page, { treeOnly: true }) Snap->>Snap: Build Frame Context (iframes/shadow) loop For each Frame in Scope Snap->>Frame: a11yForFrame(frame, { hashMode: true }) Frame->>CDP: Fetch Accessibility Tree nodes CDP-->>Frame: A11y Node Tree Frame->>Frame: decorateRoles() & buildHierarchicalTree() loop For each Node in Tree alt CHANGED: hashMode is active Frame->>Fmt: NEW: formatTreeLineForHash(node) Fmt->>Fmt: Normalize structural roles (div/span -> "none") Fmt->>Fmt: Quote names and keep [encodedId] else Standard mode Frame->>Fmt: formatTreeLine(node) end Fmt-->>Frame: Formatted string line end Frame-->>Snap: Frame outline (string) end Snap->>Snap: mergeFramesIntoSnapshot() Note right of Snap: Injects iframe subtrees into parent outlines
using [encodedId] markers alt NEW: treeOnly is requested Snap->>Snap: NEW: stripIds(combinedTree) Note right of Snap: Final Regex pass removes all [encodedId]
prefixes for deterministic cache key Snap-->>Caller: Return deterministic string (Outline only) else Standard mode Snap-->>Caller: Return HybridSnapshot object end ```

_{Reply with feedback, questions, or to request a fix. Tag `@cubic-dev-ai` to re-run a review.}