@descryy/runtime-identity-grounding 0.2.0

package/dist/element-identity.d.ts

@@ -0,0 +1,146 @@
+/**
+ * What identity grounding is allowed to say about one on-screen element.
+ *
+ * The whole package answers a single question — *which component produced
+ * this DOM node, and where is that written* — and this file fixes the
+ * vocabulary of the answer so that "we could not tell" is a first-class,
+ * named value rather than a null a reader has to interpret.
+ *
+ * ## No new event type, no new node type
+ *
+ * `RuntimeEventType` (`@descryy/runtime-contracts`) gains nothing here, and
+ * neither does `descry-core`'s frozen 15/15 graph vocabulary. This follows
+ * `@descryy/runtime-browser`'s `dom-evidence.ts` precedent exactly: a DOM
+ * fact is naturally *"what did the element this action touched look like"*,
+ * not an independent stream, so it rides on the `Evidence.payload` of the
+ * action evidence a caller is already emitting. An `ElementIdentity` is a
+ * plain, JSON-serialisable object for exactly that reason.
+ *
+ * The graph side is the same discipline one layer over: this package
+ * resolves an element to a **file, a symbol name and a line**, which is
+ * precisely `resolveSymbolNode`'s (`@descryy/runtime-graph-correlator`) input.
+ * It does not resolve to a node id itself — that resolver already refuses
+ * ambiguity, checks the line against the node's range and knows about
+ * repo-relative versus absolute path languages, and a second copy of that
+ * reasoning here would be a copy that drifts. See `graph-join.ts`.
+ */
+import type { CapabilityStatus, SourceLocation } from "@descryy/runtime-contracts";
+/**
+ * Every way this can decline to name a component, as a closed set.
+ *
+ * A refusal is not an error and is never thrown — same contract
+ * `CollectorStartResult` states for a collector that cannot start: absence
+ * has to be representable data the caller can act on.
+ */
+export declare const IDENTITY_REFUSALS: readonly ["probe-not-installed", "element-not-found", "not-react", "react-debug-fields-absent", "no-component-fiber", "anonymous-component"];
+export type IdentityRefusal = (typeof IDENTITY_REFUSALS)[number];
+/**
+ * How a source location was obtained. The two values are the two React
+ * majors' genuinely different internals, not two implementations of one
+ * idea — see `identity-grounding.ts` for the measurements.
+ */
+export declare const GROUNDING_MECHANISMS: readonly ["react-debug-source", "react-owner-stack"];
+export type GroundingMechanism = (typeof GROUNDING_MECHANISMS)[number];
+export declare const COMPONENT_KINDS: readonly ["function", "class", "forward-ref", "memo"];
+export type ComponentKind = (typeof COMPONENT_KINDS)[number];
+export declare const COMPONENT_NAME_SOURCES: readonly ["displayName", "function-name", "forward-ref-render-name"];
+export type ComponentNameSource = (typeof COMPONENT_NAME_SOURCES)[number];
+export interface ResolvedComponent {
+    readonly name: string;
+    /** Which property the name actually came from — a `displayName` a developer set and a minifier-surviving `function.name` are not equally trustworthy, and a reader should be able to tell them apart. */
+    readonly nameSource: ComponentNameSource;
+    readonly kind: ComponentKind;
+}
+/**
+ * Which fiber field the component was read from.
+ *
+ * `_debugOwner` is React's own record of **which component's render created
+ * this element**, and it is the one that pairs with the source location:
+ * `_debugSource` and `_debugStack` both describe the *creation* site. The
+ * `return` chain answers a different question — which component this
+ * element ended up rendered *inside* — and the two differ whenever an
+ * element is created in one component and passed down as `children` to
+ * another. The fixture app renders exactly that case on purpose.
+ */
+export declare const COMPONENT_SOURCES: readonly ["debug-owner", "return-chain"];
+export type ComponentSource = (typeof COMPONENT_SOURCES)[number];
+interface ElementIdentityBase {
+    readonly selector: string;
+    /**
+     * How many `parentElement` hops from the queried element to the node that
+     * actually carried a React fiber. `0` is the element itself. Greater than
+     * zero means the queried node was not created by React at all — the
+     * inside of a `dangerouslySetInnerHTML` block, say — and the answer
+     * describes its nearest React-rendered ancestor. Stated, never folded
+     * into the answer silently.
+     */
+    readonly fiberDistance: number;
+}
+export interface ElementIdentityGrounded extends ElementIdentityBase {
+    readonly outcome: "grounded";
+    /** The component whose render created this element. */
+    readonly component: ResolvedComponent;
+    readonly componentSource: ComponentSource;
+    /** The nearest component in the `return` chain — where the element was rendered, as opposed to where it was created. Null when there is none above the host fiber. */
+    readonly renderedBy: ResolvedComponent | null;
+    readonly sourceLocation: SourceLocation;
+    /**
+     * True when `sourceLocation.file` names authored source. False when it
+     * names compiled output because nothing could map it back — a React 19
+     * owner stack with no source map beside the bundle. The location is still
+     * real and still worth reporting; it just is not the file a developer
+     * wrote, and `capability` degrades accordingly.
+     */
+    readonly authoredSource: boolean;
+    readonly mechanism: GroundingMechanism;
+    readonly capability: CapabilityStatus;
+}
+export interface ElementIdentityComponentOnly extends ElementIdentityBase {
+    readonly outcome: "component-only";
+    /** The component is named and trustworthy — this is a development build — but no source location could be produced for it. */
+    readonly component: ResolvedComponent;
+    readonly componentSource: ComponentSource;
+    readonly renderedBy: ResolvedComponent | null;
+    readonly capability: CapabilityStatus;
+    readonly reason: string;
+}
+export interface ElementIdentityRefused extends ElementIdentityBase {
+    readonly outcome: "refused";
+    readonly refusal: IdentityRefusal;
+    readonly reason: string;
+    readonly capability: CapabilityStatus;
+    /**
+     * The running page's own `type.name` for the fiber, when there was a
+     * fiber at all.
+     *
+     * **Not a component name**, and deliberately not called one. On the
+     * `react-debug-fields-absent` path this is a minified identifier, kept so
+     * a human debugging a refusal can see what was actually there. Anything
+     * that treats this as an authored name has reintroduced exactly the guess
+     * the refusal exists to prevent.
+     */
+    readonly observedTypeName: string | null;
+}
+export type ElementIdentity = ElementIdentityGrounded | ElementIdentityComponentOnly | ElementIdentityRefused;
+/**
+ * The capability level this answer reports, in `CollectorCapabilities`'s own
+ * three-value vocabulary (`@descryy/runtime-contracts`) rather than a fourth
+ * one invented here.
+ *
+ * The mapping, stated once so it cannot drift between call sites:
+ *
+ * | outcome | availability | why |
+ * | --- | --- | --- |
+ * | `grounded`, authored source, not stale | `available` | component and authored file/line, both trustworthy |
+ * | `grounded`, compiled or stale location | `degraded` | a real location that is not the authored one, or one whose freshness failed a check |
+ * | `component-only` | `degraded` | the component is named; no location at all |
+ * | `refused` | `unavailable` | nothing was named |
+ *
+ * `unavailable` is this repo's existing word for what a refusal is; there is
+ * no `refused` member of `CapabilityAvailability` and adding one would fork
+ * the capability model for one package.
+ */
+export declare function capabilityFor(availability: "available"): CapabilityStatus;
+export declare function capabilityFor(availability: "degraded" | "unavailable", reason: string): CapabilityStatus;
+export {};
+//# sourceMappingURL=element-identity.d.ts.map

package/dist/element-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-identity.d.ts","sourceRoot":"","sources":["../src/element-identity.ts"],"names":[],"mappings":"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"}

package/dist/element-identity.js

@@ -0,0 +1,99 @@
+/**
+ * What identity grounding is allowed to say about one on-screen element.
+ *
+ * The whole package answers a single question — *which component produced
+ * this DOM node, and where is that written* — and this file fixes the
+ * vocabulary of the answer so that "we could not tell" is a first-class,
+ * named value rather than a null a reader has to interpret.
+ *
+ * ## No new event type, no new node type
+ *
+ * `RuntimeEventType` (`@descryy/runtime-contracts`) gains nothing here, and
+ * neither does `descry-core`'s frozen 15/15 graph vocabulary. This follows
+ * `@descryy/runtime-browser`'s `dom-evidence.ts` precedent exactly: a DOM
+ * fact is naturally *"what did the element this action touched look like"*,
+ * not an independent stream, so it rides on the `Evidence.payload` of the
+ * action evidence a caller is already emitting. An `ElementIdentity` is a
+ * plain, JSON-serialisable object for exactly that reason.
+ *
+ * The graph side is the same discipline one layer over: this package
+ * resolves an element to a **file, a symbol name and a line**, which is
+ * precisely `resolveSymbolNode`'s (`@descryy/runtime-graph-correlator`) input.
+ * It does not resolve to a node id itself — that resolver already refuses
+ * ambiguity, checks the line against the node's range and knows about
+ * repo-relative versus absolute path languages, and a second copy of that
+ * reasoning here would be a copy that drifts. See `graph-join.ts`.
+ */
+/**
+ * Every way this can decline to name a component, as a closed set.
+ *
+ * A refusal is not an error and is never thrown — same contract
+ * `CollectorStartResult` states for a collector that cannot start: absence
+ * has to be representable data the caller can act on.
+ */
+export const IDENTITY_REFUSALS = [
+    /** `install()` was never called, or was called after the document had already loaded — `page.addInitScript` does not reach a document that is already there. */
+    "probe-not-installed",
+    /** The selector matched nothing in the page. */
+    "element-not-found",
+    /** Neither the element nor any ancestor carries a React fiber key. Not a React tree — or not one this React version tags on the host node. */
+    "not-react",
+    /**
+     * A fiber was found and it carries no `_debug*` field of any kind.
+     *
+     * **This is the production-build refusal, and it is the one that must
+     * never soften into a guess.** React strips `_debugSource` /
+     * `_debugOwner` / `_debugStack` from fibers outside a development build,
+     * and a production bundle is additionally minified, so `type.name` on the
+     * fiber is whatever the minifier left behind — `U2`, `ap` — not the
+     * authored component name. Measured directly against React 18.3.1 and
+     * 19.2.8 production bundles: zero `_debug*` keys, and component names
+     * mangled in both.
+     *
+     * So there are two independent losses here, not one: no source location,
+     * *and* no trustworthy name. Reporting the mangled name as the component
+     * would be a confident wrong answer, which is worse than this refusal.
+     * The observed `type.name` still travels on
+     * `ElementIdentityRefused.observedTypeName`, labelled as what it is.
+     *
+     * The second, far rarer reading of the same observation — a React version
+     * that stopped exposing `_debug*` in development too — cannot be
+     * distinguished from here, which is why this is named for the evidence
+     * (the fields are absent) rather than for the conclusion (it is a
+     * production build). The reason string carries both readings.
+     */
+    "react-debug-fields-absent",
+    /** A host fiber with no component above it at all — an element rendered directly by the root, with no `_debugOwner` and no component in its `return` chain. */
+    "no-component-fiber",
+    /** A component fiber was found and it has no resolvable name (an anonymous function or arrow with no `displayName`). Refused rather than reported as a nameless component: `resolveSymbolNode` has nothing to look up, and neither does a reader. */
+    "anonymous-component",
+];
+/**
+ * How a source location was obtained. The two values are the two React
+ * majors' genuinely different internals, not two implementations of one
+ * idea — see `identity-grounding.ts` for the measurements.
+ */
+export const GROUNDING_MECHANISMS = [
+    /** React 18 and earlier, development build: `fiber._debugSource`, which names the authored file and line directly. */
+    "react-debug-source",
+    /** React 19, development build: `fiber._debugStack`, a captured `Error` whose frames point into *compiled* output and must be mapped back. */
+    "react-owner-stack",
+];
+export const COMPONENT_KINDS = ["function", "class", "forward-ref", "memo"];
+export const COMPONENT_NAME_SOURCES = ["displayName", "function-name", "forward-ref-render-name"];
+/**
+ * Which fiber field the component was read from.
+ *
+ * `_debugOwner` is React's own record of **which component's render created
+ * this element**, and it is the one that pairs with the source location:
+ * `_debugSource` and `_debugStack` both describe the *creation* site. The
+ * `return` chain answers a different question — which component this
+ * element ended up rendered *inside* — and the two differ whenever an
+ * element is created in one component and passed down as `children` to
+ * another. The fixture app renders exactly that case on purpose.
+ */
+export const COMPONENT_SOURCES = ["debug-owner", "return-chain"];
+export function capabilityFor(availability, reason) {
+    return availability === "available" ? { availability, reason: null } : { availability, reason: reason ?? "" };
+}
+//# sourceMappingURL=element-identity.js.map

package/dist/element-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-identity.js","sourceRoot":"","sources":["../src/element-identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,gKAAgK;IAChK,qBAAqB;IACrB,gDAAgD;IAChD,mBAAmB;IACnB,8IAA8I;IAC9I,WAAW;IACX;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,2BAA2B;IAC3B,+JAA+J;IAC/J,oBAAoB;IACpB,qPAAqP;IACrP,qBAAqB;CACb,CAAC;AAGX;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,sHAAsH;IACtH,oBAAoB;IACpB,8IAA8I;IAC9I,mBAAmB;CACX,CAAC;AAGX,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,UAAU,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,CAAU,CAAC;AAGrF,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,aAAa,EAAE,eAAe,EAAE,yBAAyB,CAAU,CAAC;AAU3G;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,aAAa,EAAE,cAAc,CAAU,CAAC;AAsF1E,MAAM,UAAU,aAAa,CAAC,YAA8C,EAAE,MAAe;IAC3F,OAAO,YAAY,KAAK,WAAW,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,IAAI,EAAE,EAAE,CAAC;AAChH,CAAC"}

package/dist/fiber-probe.d.ts

@@ -0,0 +1,112 @@
+/**
+ * The page-side half: reads React's fiber bookkeeping off a real DOM node
+ * and returns **raw facts only**.
+ *
+ * ## Read-only, and why that matters here
+ *
+ * `frontend-initiator-capture.ts` (`@descryy/runtime-browser`) had to open
+ * its own module comment by conceding that it *writes* — it wraps
+ * `window.fetch` and adds a header to real outgoing requests, which is a
+ * real observable side effect on the application under test. This module
+ * has no such concession to make. It defines one function on `window` and
+ * reads properties React already put on DOM nodes and on its own fiber
+ * objects. Nothing is wrapped, nothing is patched, no application code path
+ * changes shape because Descry is attached. That is the same
+ * observation-only guarantee `Collector` states for attach mode
+ * (`ATTACH_MODE_SCOPE_DISCLOSURE`), and it holds here without needing an
+ * exception.
+ *
+ * ## Injected through the existing seam, not a second one
+ *
+ * `page.addInitScript` with a string body — exactly the mechanism
+ * `frontend-initiator-capture.ts` already uses, for the same reason it
+ * gives: the script runs as written in the page's own JS engine and needs
+ * no transpilation step of its own. It is a string rather than a typed
+ * function because this repo's `tsconfig.base.json` compiles with `lib:
+ * ["ES2023"]` and no DOM library at all, so `document` and `window` do not
+ * exist as types in this package. Writing the page code as a string is not
+ * a shortcut around that; it is the same choice the sibling module made,
+ * and it keeps the boundary between "runs here" and "runs there" visible.
+ *
+ * `addInitScript` does not reach a document that has already loaded. Call
+ * `install()` before navigating, like every other collector in
+ * `@descryy/runtime-browser` — a page navigated first reports
+ * `probe-not-installed`, by name, rather than silently returning nothing.
+ *
+ * ## Raw facts only — no decisions
+ *
+ * Everything this returns is a JSON-serialisable transcript of what was on
+ * the fiber. Deciding what it *means* (is this a production build? does
+ * this owner stack point at authored source?) happens in Node, in
+ * `identity-grounding.ts`, where it can be unit-tested without a browser
+ * and where the source-map machinery this repo already owns is reachable.
+ * The page-side script cannot resolve a source map and must not try.
+ */
+import type { Page } from "playwright-core";
+import type { ComponentKind, ComponentNameSource } from "./element-identity.ts";
+/** The single global this installs. One name, one function, no other footprint on the page. */
+export declare const IDENTITY_GROUNDING_BINDING = "__descryIdentityGrounding";
+/**
+ * The two key prefixes React has used to hang a fiber off a host DOM node:
+ * `__reactFiber$` since React 17, `__reactInternalInstance$` before that.
+ * Both are checked because both are cheap to check and a wrong "not React"
+ * answer on a React 16 page would be a silent, permanent blind spot.
+ *
+ * Measured present as `__reactFiber$<random>` on React 18.3.1 and 19.2.8
+ * alike; `__reactInternalInstance$` is carried on the documented shape of
+ * React 16 and is **not** covered by this repo's fixtures, which is stated
+ * here rather than implied by the code.
+ */
+export declare const FIBER_KEY_PREFIXES: readonly ["__reactFiber$", "__reactInternalInstance$"];
+export type FiberKeyPrefix = (typeof FIBER_KEY_PREFIXES)[number];
+/** A component's name as the page could read it, or an explicit "there was a component and it has no name". */
+export interface RawComponentDescriptor {
+    readonly name: string | null;
+    readonly nameSource: ComponentNameSource | null;
+    readonly kind: ComponentKind;
+}
+export interface RawDebugSource {
+    readonly fileName: string | null;
+    readonly lineNumber: number | null;
+    readonly columnNumber: number | null;
+}
+export type RawFiberProbe = {
+    readonly status: "probe-not-installed";
+} | {
+    readonly status: "element-not-found";
+    readonly selector: string;
+} | {
+    readonly status: "no-fiber";
+    readonly selector: string;
+    /** The element's own enumerable keys, capped — so a "not React" refusal can be argued with rather than merely believed. */
+    readonly ownKeys: readonly string[];
+} | {
+    readonly status: "fiber";
+    readonly selector: string;
+    readonly fiberKeyPrefix: FiberKeyPrefix;
+    readonly fiberDistance: number;
+    /** `fiber.tag`, verbatim, for audit only. Nothing in this package branches on it — see `describeType` in the injected script for why the type shape is used instead. */
+    readonly hostTag: number | null;
+    /** `fiber.type` when it is a string, i.e. the host element's tag name. Null for a non-host fiber. */
+    readonly hostTypeName: string | null;
+    /** Every `_debug*` key present on the host fiber. Empty means a non-development React build — the one fact the production refusal rests on. */
+    readonly debugFields: readonly string[];
+    /** `fiber._debugOwner`'s type, described. Null when there is no owner, or the owner is not a nameable component (a host root, a context provider). */
+    readonly owner: RawComponentDescriptor | null;
+    /** The nearest nameable component walking `fiber.return`. Null when there is none. */
+    readonly returnChainComponent: RawComponentDescriptor | null;
+    /** React 18 and earlier, development: the authored file/line the JSX transform recorded. */
+    readonly debugSource: RawDebugSource | null;
+    /** React 19, development: `fiber._debugStack.stack`, verbatim. Frames point into compiled output. */
+    readonly debugStackText: string | null;
+    /** `type.name` off the host fiber's own type when it is not a string — kept for the refusal path, never treated as an authored name. */
+    readonly observedTypeName: string | null;
+};
+export interface IdentityGroundingProbe {
+    /** Installs the page-side reader into every document this page loads from now on. Call before navigating. */
+    install(page: Page): Promise<void>;
+    /** Runs the reader against one selector in the page's current document. */
+    probe(page: Page, selector: string): Promise<RawFiberProbe>;
+}
+export declare function createIdentityGroundingProbe(): IdentityGroundingProbe;
+//# sourceMappingURL=fiber-probe.d.ts.map

package/dist/fiber-probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fiber-probe.d.ts","sourceRoot":"","sources":["../src/fiber-probe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAEhF,+FAA+F;AAC/F,eAAO,MAAM,0BAA0B,8BAA8B,CAAC;AAEtE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,wDAAyD,CAAC;AACzF,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjE,+GAA+G;AAC/G,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAChD,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;CAC9B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAED,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAA;CAAE,GAC1C;IAAE,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACnE;IACE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2HAA2H;IAC3H,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC,GACD;IACE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,wKAAwK;IACxK,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,qGAAqG;IACrG,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,+IAA+I;IAC/I,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,sJAAsJ;IACtJ,QAAQ,CAAC,KAAK,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAC9C,sFAAsF;IACtF,QAAQ,CAAC,oBAAoB,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAC7D,4FAA4F;IAC5F,QAAQ,CAAC,WAAW,EAAE,cAAc,GAAG,IAAI,CAAC;IAC5C,qGAAqG;IACrG,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,wIAAwI;IACxI,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1C,CAAC;AAEN,MAAM,WAAW,sBAAsB;IACrC,6GAA6G;IAC7G,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,2EAA2E;IAC3E,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CAC7D;AAED,wBAAgB,4BAA4B,IAAI,sBAAsB,CASrE"}

package/dist/fiber-probe.js

@@ -0,0 +1,269 @@
+/**
+ * The page-side half: reads React's fiber bookkeeping off a real DOM node
+ * and returns **raw facts only**.
+ *
+ * ## Read-only, and why that matters here
+ *
+ * `frontend-initiator-capture.ts` (`@descryy/runtime-browser`) had to open
+ * its own module comment by conceding that it *writes* — it wraps
+ * `window.fetch` and adds a header to real outgoing requests, which is a
+ * real observable side effect on the application under test. This module
+ * has no such concession to make. It defines one function on `window` and
+ * reads properties React already put on DOM nodes and on its own fiber
+ * objects. Nothing is wrapped, nothing is patched, no application code path
+ * changes shape because Descry is attached. That is the same
+ * observation-only guarantee `Collector` states for attach mode
+ * (`ATTACH_MODE_SCOPE_DISCLOSURE`), and it holds here without needing an
+ * exception.
+ *
+ * ## Injected through the existing seam, not a second one
+ *
+ * `page.addInitScript` with a string body — exactly the mechanism
+ * `frontend-initiator-capture.ts` already uses, for the same reason it
+ * gives: the script runs as written in the page's own JS engine and needs
+ * no transpilation step of its own. It is a string rather than a typed
+ * function because this repo's `tsconfig.base.json` compiles with `lib:
+ * ["ES2023"]` and no DOM library at all, so `document` and `window` do not
+ * exist as types in this package. Writing the page code as a string is not
+ * a shortcut around that; it is the same choice the sibling module made,
+ * and it keeps the boundary between "runs here" and "runs there" visible.
+ *
+ * `addInitScript` does not reach a document that has already loaded. Call
+ * `install()` before navigating, like every other collector in
+ * `@descryy/runtime-browser` — a page navigated first reports
+ * `probe-not-installed`, by name, rather than silently returning nothing.
+ *
+ * ## Raw facts only — no decisions
+ *
+ * Everything this returns is a JSON-serialisable transcript of what was on
+ * the fiber. Deciding what it *means* (is this a production build? does
+ * this owner stack point at authored source?) happens in Node, in
+ * `identity-grounding.ts`, where it can be unit-tested without a browser
+ * and where the source-map machinery this repo already owns is reachable.
+ * The page-side script cannot resolve a source map and must not try.
+ */
+/** The single global this installs. One name, one function, no other footprint on the page. */
+export const IDENTITY_GROUNDING_BINDING = "__descryIdentityGrounding";
+/**
+ * The two key prefixes React has used to hang a fiber off a host DOM node:
+ * `__reactFiber$` since React 17, `__reactInternalInstance$` before that.
+ * Both are checked because both are cheap to check and a wrong "not React"
+ * answer on a React 16 page would be a silent, permanent blind spot.
+ *
+ * Measured present as `__reactFiber$<random>` on React 18.3.1 and 19.2.8
+ * alike; `__reactInternalInstance$` is carried on the documented shape of
+ * React 16 and is **not** covered by this repo's fixtures, which is stated
+ * here rather than implied by the code.
+ */
+export const FIBER_KEY_PREFIXES = ["__reactFiber$", "__reactInternalInstance$"];
+export function createIdentityGroundingProbe() {
+    return {
+        async install(page) {
+            await page.addInitScript({ content: probeScriptSource() });
+        },
+        probe(page, selector) {
+            return page.evaluate(probeCallSource(selector));
+        },
+    };
+}
+/**
+ * The call side, also a string — and a **self-invoking** one, with the
+ * selector serialised into it rather than passed as an `evaluate` argument.
+ *
+ * Measured, not stylistic: Playwright's string form of `page.evaluate`
+ * evaluates the text as an expression, and passing a separate `arg`
+ * alongside a string body returned `undefined` here rather than calling the
+ * function expression with it. A self-invoking expression has one
+ * unambiguous meaning in both directions, and `JSON.stringify` on the
+ * selector is the same escaping this file already uses for the binding
+ * name, so a selector containing quotes cannot break out of the string.
+ *
+ * The `probe-not-installed` branch lives here rather than in the injected
+ * script for the obvious reason that a script which never ran cannot report
+ * that it never ran. This is the only place that distinction can be drawn,
+ * and drawing it is what keeps "Descry was not attached to this document"
+ * from being reported as "this page is not React".
+ */
+function probeCallSource(selector) {
+    return `(() => {
+  const grounding = window[${JSON.stringify(IDENTITY_GROUNDING_BINDING)}];
+  if (grounding === undefined || typeof grounding.probe !== "function") {
+    return { status: "probe-not-installed" };
+  }
+  return grounding.probe(${JSON.stringify(selector)});
+})()`;
+}
+/** Cap on the key list carried by a `no-fiber` result. A `<div>` has few own keys; a pathological one should not become an unbounded payload. */
+const MAX_REPORTED_OWN_KEYS = 32;
+/**
+ * The injected reader.
+ *
+ * ## Why component detection reads the *type shape* and not `fiber.tag`
+ *
+ * The obvious implementation is a set of numeric fiber tags —
+ * `0 = FunctionComponent`, `1 = ClassComponent`, `11 = ForwardRef` and so
+ * on. That table is a private React implementation detail with no
+ * compatibility guarantee across majors, and this module has to work
+ * against at least two majors whose fiber internals already differ in the
+ * ways this package exists to handle. A table that is wrong on some future
+ * React does not fail loudly — it silently classifies a real component as
+ * "not a component" and the answer degrades to a refusal nobody can
+ * explain.
+ *
+ * `fiber.type` is far more stable and is directly observable: a string is a
+ * host element, a function is a function or class component, an object with
+ * a `render` is a `forwardRef`, an object with a `type` is a `memo`. That
+ * is what is used. `tag` is still reported, verbatim, for audit.
+ *
+ * ## Everything degrades to null, nothing throws
+ *
+ * A property access that finds an unexpected shape yields `null`, and the
+ * whole probe body is wrapped so that a genuinely unexpected page cannot
+ * turn a read-only observation into a page error the application would
+ * then have to survive.
+ */
+function probeScriptSource() {
+    return `(() => {
+  const FIBER_KEY_PREFIXES = ${JSON.stringify(FIBER_KEY_PREFIXES)};
+
+  function fiberKeyOf(element) {
+    const keys = Object.keys(element);
+    for (let i = 0; i < keys.length; i++) {
+      for (let p = 0; p < FIBER_KEY_PREFIXES.length; p++) {
+        if (keys[i].indexOf(FIBER_KEY_PREFIXES[p]) === 0) {
+          return { key: keys[i], prefix: FIBER_KEY_PREFIXES[p] };
+        }
+      }
+    }
+    return null;
+  }
+
+  function named(type, kind) {
+    if (typeof type.displayName === "string" && type.displayName.length > 0) {
+      return { name: type.displayName, nameSource: "displayName", kind: kind };
+    }
+    if (typeof type.name === "string" && type.name.length > 0) {
+      return { name: type.name, nameSource: "function-name", kind: kind };
+    }
+    return null;
+  }
+
+  function describeType(type) {
+    if (type === null || type === undefined) return null;
+    // A host element ("div", "button"). Real, but not a component.
+    if (typeof type === "string") return null;
+    if (typeof type === "function") {
+      const kind = type.prototype !== undefined && type.prototype !== null && type.prototype.isReactComponent !== undefined
+        ? "class"
+        : "function";
+      return named(type, kind) || { name: null, nameSource: null, kind: kind };
+    }
+    if (typeof type === "object") {
+      if (typeof type.render === "function") {
+        const outer = named(type, "forward-ref");
+        if (outer !== null) return outer;
+        const inner = named(type.render, "forward-ref");
+        if (inner !== null) return { name: inner.name, nameSource: "forward-ref-render-name", kind: "forward-ref" };
+        return { name: null, nameSource: null, kind: "forward-ref" };
+      }
+      if (type.type !== undefined && type.type !== null) {
+        const outer = named(type, "memo");
+        if (outer !== null) return outer;
+        const inner = describeType(type.type);
+        if (inner !== null) return { name: inner.name, nameSource: inner.nameSource, kind: "memo" };
+        return { name: null, nameSource: null, kind: "memo" };
+      }
+      // A context provider/consumer, a portal, a fragment: a real fiber,
+      // and not something with an authored component name to report.
+      return null;
+    }
+    return null;
+  }
+
+  function nearestComponentAbove(fiber) {
+    let current = fiber.return;
+    let hops = 0;
+    while (current !== null && current !== undefined && hops < 200) {
+      const described = describeType(current.type);
+      if (described !== null) return described;
+      current = current.return;
+      hops++;
+    }
+    return null;
+  }
+
+  function debugSourceOf(fiber) {
+    const source = fiber._debugSource;
+    if (source === null || source === undefined || typeof source !== "object") return null;
+    return {
+      fileName: typeof source.fileName === "string" ? source.fileName : null,
+      lineNumber: typeof source.lineNumber === "number" ? source.lineNumber : null,
+      columnNumber: typeof source.columnNumber === "number" ? source.columnNumber : null,
+    };
+  }
+
+  function debugStackTextOf(fiber) {
+    const stack = fiber._debugStack;
+    if (stack === null || stack === undefined) return null;
+    return typeof stack.stack === "string" ? stack.stack : null;
+  }
+
+  window[${JSON.stringify(IDENTITY_GROUNDING_BINDING)}] = {
+    probe: function (selector) {
+      let element;
+      try {
+        element = document.querySelector(selector);
+      } catch (_error) {
+        // An invalid selector is the caller's mistake, and it is not a
+        // statement about the page. Reported as "matched nothing", which is
+        // what actually happened here.
+        return { status: "element-not-found", selector: selector };
+      }
+      if (element === null) return { status: "element-not-found", selector: selector };
+
+      let node = element;
+      let distance = 0;
+      let located = null;
+      while (node !== null && node !== undefined) {
+        const found = fiberKeyOf(node);
+        if (found !== null) {
+          located = { node: node, key: found.key, prefix: found.prefix };
+          break;
+        }
+        node = node.parentElement;
+        distance++;
+      }
+      if (located === null) {
+        return {
+          status: "no-fiber",
+          selector: selector,
+          ownKeys: Object.keys(element).slice(0, ${MAX_REPORTED_OWN_KEYS}),
+        };
+      }
+
+      const fiber = located.node[located.key];
+      const owner = fiber._debugOwner;
+      const observedType = fiber.type;
+
+      return {
+        status: "fiber",
+        selector: selector,
+        fiberKeyPrefix: located.prefix,
+        fiberDistance: distance,
+        hostTag: typeof fiber.tag === "number" ? fiber.tag : null,
+        hostTypeName: typeof observedType === "string" ? observedType : null,
+        debugFields: Object.keys(fiber).filter(function (key) { return key.indexOf("_debug") === 0; }),
+        owner: owner === null || owner === undefined ? null : describeType(owner.type),
+        returnChainComponent: nearestComponentAbove(fiber),
+        debugSource: debugSourceOf(fiber),
+        debugStackText: debugStackTextOf(fiber),
+        observedTypeName:
+          observedType !== null && observedType !== undefined && typeof observedType !== "string" && typeof observedType.name === "string"
+            ? observedType.name
+            : null,
+      };
+    },
+  };
+})();`;
+}
+//# sourceMappingURL=fiber-probe.js.map

package/dist/fiber-probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fiber-probe.js","sourceRoot":"","sources":["../src/fiber-probe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAMH,+FAA+F;AAC/F,MAAM,CAAC,MAAM,0BAA0B,GAAG,2BAA2B,CAAC;AAEtE;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,eAAe,EAAE,0BAA0B,CAAU,CAAC;AAuDzF,MAAM,UAAU,4BAA4B;IAC1C,OAAO;QACL,KAAK,CAAC,OAAO,CAAC,IAAU;YACtB,MAAM,IAAI,CAAC,aAAa,CAAC,EAAE,OAAO,EAAE,iBAAiB,EAAE,EAAE,CAAC,CAAC;QAC7D,CAAC;QACD,KAAK,CAAC,IAAU,EAAE,QAAgB;YAChC,OAAO,IAAI,CAAC,QAAQ,CAAgB,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAC;QACjE,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAS,eAAe,CAAC,QAAgB;IACvC,OAAO;6BACoB,IAAI,CAAC,SAAS,CAAC,0BAA0B,CAAC;;;;2BAI5C,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC;KAC9C,CAAC;AACN,CAAC;AAED,iJAAiJ;AACjJ,MAAM,qBAAqB,GAAG,EAAE,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,SAAS,iBAAiB;IACxB,OAAO;+BACsB,IAAI,CAAC,SAAS,CAAC,kBAAkB,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAoFtD,IAAI,CAAC,SAAS,CAAC,0BAA0B,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mDA6BF,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;MA2BlE,CAAC;AACP,CAAC"}