Own CDP frame applicability and identity at the parsed event boundary. Preserve malformed or incomplete main-frame facts, recognize replacement roots, and carry the same document identity through captures, screenshots, timelines, and execution windows. Validation: full check:ci and docs:check; 763 browser and dispatch tests passed, 6 skipped. Independent source and fixture-lifecycle review passed. Local real-Chrome behavior was not exercised. Closes #5665
225 lines
6.9 KiB
TypeScript
225 lines
6.9 KiB
TypeScript
import {
|
|
isHttpUrl,
|
|
numberValue,
|
|
recordValue,
|
|
recordsValue,
|
|
cdpStringValue,
|
|
type UnknownRecord,
|
|
} from "./CdpCaptureValues.js";
|
|
import type { CdpEvent } from "./CdpConnection.js";
|
|
|
|
export type FrameSelection = "main" | "other" | "unknown";
|
|
export type FrameParentRelation =
|
|
| "root"
|
|
| "child"
|
|
| "unknown"
|
|
| "not_applicable";
|
|
|
|
/** Normalized frame identity facts shared by all selected-frame consumers. */
|
|
export interface CdpFrameIdentity {
|
|
readonly applicability: "applicable" | "not_applicable";
|
|
readonly selection: FrameSelection;
|
|
readonly isRootReplacement: boolean;
|
|
readonly frameId: string | null;
|
|
readonly identityIssue:
|
|
| "missing_params"
|
|
| "invalid_params"
|
|
| "missing_frame"
|
|
| "missing_id"
|
|
| "invalid_id"
|
|
| null;
|
|
readonly parentRelation: FrameParentRelation;
|
|
readonly parentId: string | null;
|
|
readonly parentIssue:
|
|
| "invalid_parent_id"
|
|
| "self_parent"
|
|
| "main_frame_has_parent"
|
|
| null;
|
|
}
|
|
|
|
const nonEmptyString = (value: unknown): string | undefined =>
|
|
typeof value === "string" && value.length > 0 ? value : undefined;
|
|
|
|
const identityIssueFor = (
|
|
navigated: boolean,
|
|
frame: UnknownRecord | undefined,
|
|
rawId: unknown,
|
|
): CdpFrameIdentity["identityIssue"] => {
|
|
if (navigated && frame === undefined) return "missing_frame";
|
|
if (rawId === undefined) return "missing_id";
|
|
return nonEmptyString(rawId) === undefined ? "invalid_id" : null;
|
|
};
|
|
|
|
const parentFacts = (
|
|
navigated: boolean,
|
|
frame: UnknownRecord | undefined,
|
|
): Pick<CdpFrameIdentity, "parentRelation" | "parentId" | "parentIssue"> => {
|
|
if (!navigated)
|
|
return {
|
|
parentRelation: "not_applicable",
|
|
parentId: null,
|
|
parentIssue: null,
|
|
};
|
|
if (frame === undefined)
|
|
return { parentRelation: "unknown", parentId: null, parentIssue: null };
|
|
if (!("parentId" in frame))
|
|
return { parentRelation: "root", parentId: null, parentIssue: null };
|
|
const parentId = nonEmptyString(frame.parentId);
|
|
return parentId === undefined || parentId === nonEmptyString(frame.id)
|
|
? {
|
|
parentRelation: "unknown",
|
|
parentId: null,
|
|
parentIssue:
|
|
parentId === undefined ? "invalid_parent_id" : "self_parent",
|
|
}
|
|
: { parentRelation: "child", parentId, parentIssue: null };
|
|
};
|
|
|
|
/** Parse required frame identity separately from the optional parent fact. */
|
|
export const cdpFrameIdentity = (
|
|
event: CdpEvent,
|
|
mainFrameId: string,
|
|
): CdpFrameIdentity => {
|
|
const navigated = event.method === "Page.frameNavigated";
|
|
const requested = event.method === "Page.frameRequestedNavigation";
|
|
const sameDocument = event.method === "Page.navigatedWithinDocument";
|
|
if (!navigated && !requested && !sameDocument)
|
|
return {
|
|
applicability: "not_applicable",
|
|
selection: "unknown",
|
|
isRootReplacement: false,
|
|
frameId: null,
|
|
identityIssue: null,
|
|
parentRelation: "not_applicable",
|
|
parentId: null,
|
|
parentIssue: null,
|
|
};
|
|
const params = recordValue(event.params);
|
|
if (params === undefined)
|
|
return {
|
|
applicability: "applicable",
|
|
selection: "unknown",
|
|
isRootReplacement: false,
|
|
frameId: null,
|
|
identityIssue:
|
|
event.params === undefined ? "missing_params" : "invalid_params",
|
|
parentRelation: "not_applicable",
|
|
parentId: null,
|
|
parentIssue: null,
|
|
};
|
|
const frame = navigated ? recordValue(params.frame) : undefined;
|
|
const rawId = navigated ? frame?.id : params.frameId;
|
|
const frameId = nonEmptyString(rawId);
|
|
const selection =
|
|
frameId === undefined
|
|
? "unknown"
|
|
: frameId === mainFrameId
|
|
? "main"
|
|
: "other";
|
|
const identityIssue = identityIssueFor(navigated, frame, rawId);
|
|
const parent = parentFacts(navigated, frame);
|
|
return {
|
|
applicability: "applicable",
|
|
selection,
|
|
isRootReplacement:
|
|
selection === "other" && parent.parentRelation === "root",
|
|
frameId: frameId ?? null,
|
|
identityIssue,
|
|
parentRelation: parent.parentRelation,
|
|
parentId: parent.parentId,
|
|
parentIssue:
|
|
selection === "main" &&
|
|
(parent.parentRelation === "child" ||
|
|
parent.parentIssue === "self_parent")
|
|
? "main_frame_has_parent"
|
|
: parent.parentIssue,
|
|
};
|
|
};
|
|
|
|
export const firstCallFrame = (
|
|
value: UnknownRecord | undefined,
|
|
): UnknownRecord | undefined => recordsValue(value?.callFrames)[0];
|
|
|
|
export const initiatorLocation = (
|
|
initiator: UnknownRecord | undefined,
|
|
): UnknownRecord | undefined => {
|
|
let stack = recordValue(initiator?.stack);
|
|
for (let depth = 0; depth < 32 && stack !== undefined; depth += 1) {
|
|
const frame = firstCallFrame(stack);
|
|
if (frame !== undefined) return frame;
|
|
stack = recordValue(stack.parent);
|
|
}
|
|
return cdpStringValue(initiator?.url) === undefined ? undefined : initiator;
|
|
};
|
|
|
|
export const exclusionReasonForUrl = (
|
|
value: string | undefined,
|
|
): "disallowed_origin" | "unsupported_url" | "unattributed_origin" =>
|
|
value === undefined || value === ""
|
|
? "unattributed_origin"
|
|
: isHttpUrl(value)
|
|
? "disallowed_origin"
|
|
: "unsupported_url";
|
|
|
|
export const integerOrNull = (value: unknown): number | null => {
|
|
const number = numberValue(value);
|
|
return number === undefined ? null : Math.max(0, Math.trunc(number));
|
|
};
|
|
|
|
export const executionContextKey = (value: unknown): string | null => {
|
|
const identifier = numberValue(value);
|
|
return identifier !== undefined && Number.isSafeInteger(identifier)
|
|
? String(identifier)
|
|
: null;
|
|
};
|
|
|
|
export const isJsonContentType = (
|
|
headers: UnknownRecord | undefined,
|
|
): boolean => {
|
|
if (headers === undefined) return false;
|
|
for (const [name, value] of Object.entries(headers))
|
|
if (
|
|
name.toLowerCase() === "content-type" &&
|
|
isJsonMediaType(cdpStringValue(value))
|
|
)
|
|
return true;
|
|
return false;
|
|
};
|
|
|
|
export const isJsonMediaType = (value: string | null | undefined): boolean => {
|
|
const mediaType = value?.split(";", 1)[0]?.trim().toLowerCase();
|
|
return (
|
|
mediaType === "application/json" || mediaType?.endsWith("+json") === true
|
|
);
|
|
};
|
|
|
|
export const consolePrimitive = (
|
|
value: UnknownRecord,
|
|
): { readonly type: string; readonly text: string } | undefined => {
|
|
const type = cdpStringValue(value.type);
|
|
switch (type) {
|
|
case "string":
|
|
return typeof value.value === "string"
|
|
? { type, text: value.value }
|
|
: undefined;
|
|
case "boolean":
|
|
return typeof value.value === "boolean"
|
|
? { type, text: String(value.value) }
|
|
: undefined;
|
|
case "number":
|
|
return typeof value.value === "number"
|
|
? { type, text: String(value.value) }
|
|
: typeof value.unserializableValue === "string"
|
|
? { type, text: value.unserializableValue }
|
|
: undefined;
|
|
case "bigint":
|
|
return typeof value.unserializableValue === "string"
|
|
? { type, text: value.unserializableValue }
|
|
: undefined;
|
|
case "undefined":
|
|
return { type, text: "undefined" };
|
|
default:
|
|
return undefined;
|
|
}
|
|
};
|