@descryy/runtime-identity-grounding 0.2.0

package/dist/owner-stack.d.ts

@@ -0,0 +1,90 @@
+/**
+ * React 19's replacement for `_debugSource`, and the one rule this package
+ * needs in order to read it.
+ *
+ * ## What actually changed between the majors
+ *
+ * Measured directly, in a real Chromium, against React 18.3.1 and 19.2.8
+ * development bundles of the same authored source
+ * (`fixture-apps/react-identity`):
+ *
+ * | fiber field | React 18.3.1 dev | React 19.2.8 dev | either, production |
+ * | --- | --- | --- | --- |
+ * | `_debugSource` | `{ fileName: "src/app.jsx", lineNumber, columnNumber }` | **absent** | absent |
+ * | `_debugStack` | absent | an `Error`, message `react-stack-top-frame` | absent |
+ * | `_debugOwner` | present | present | absent |
+ * | `type.name` | authored | authored | minified |
+ *
+ * So React 19 did not move the source location, it **deleted** it and left
+ * a captured stack in its place. The stack's frames point into *compiled*
+ * output — the bundle the browser actually ran — which is why this path
+ * costs a source-map resolution that React 18's does not, and why the two
+ * mechanisms report different `SourceLocation.reliability` values
+ * (`self-contained` versus `side-artifact-resolved`). That difference is
+ * not cosmetic: one is the application telling us where it came from, the
+ * other is us translating through a file that can be missing or stale.
+ *
+ * ## The rule: drop React's own element-creation frame, and only that
+ *
+ * The captured stack's innermost frame is React's own JSX entry point:
+ *
+ * ```text
+ * Error: react-stack-top-frame
+ *     at exports.jsxDEV (http://…/dev.js:21690:32)
+ *     at PayButton     (http://…/dev.js:21714:62)   <- the site we want
+ *     at Object.react_stack_bottom_frame (…)
+ * ```
+ *
+ * The second frame is the JSX call site inside the owning component, which
+ * is exactly the fact React 18's `_debugSource` carries. Verified against
+ * the fixture: React 18 reports `src/app.jsx:20`, and mapping React 19's
+ * second frame through the bundle's source map lands on `src/app.jsx:20`
+ * as well. `react-fixtures.test.ts` asserts that equality rather than
+ * asserting each major separately, because two independently-written
+ * expectations can both be wrong in the same direction.
+ *
+ * ## Why not `stripInitiatorWrapperFrame`'s positional rule
+ *
+ * `@descryy/runtime-browser`'s initiator capture drops its first frame *by
+ * position*, and argues correctly that its own wrapper is deterministically
+ * innermost because it captured the stack itself. Nothing here captured
+ * this stack — React did — so the same reasoning is not available. Worse,
+ * `createV8StackTraceParser` **omits** frames it cannot parse a
+ * `line:column` from, so "the first frame of the parsed trace" is not
+ * reliably "the first frame of the raw text" either.
+ *
+ * The rule used instead is by name, against a closed list of React's own
+ * element-creation entry points, and it **refuses** when the innermost
+ * frame is not one of them. A refusal here costs a source location; a
+ * positional guess that is off by one costs a confident wrong file and
+ * line, attributed to a component that did not create the element. Rule 2.
+ */
+import type { StackTrace } from "@descryy/runtime-contracts";
+/**
+ * React's own element-creation entry points, matched against the **last
+ * dotted segment** of a frame's function name so that V8's `exports.jsxDEV`
+ * and a bare `jsxDEV` are the same frame.
+ *
+ * `jsxDEV` / `jsxDEVImpl` are the automatic runtime's development entry;
+ * `jsx` / `jsxs` its production ones (listed for completeness — a
+ * production build has no `_debugStack` to reach this code with);
+ * `createElement` / `createElementWithValidation` the classic runtime's.
+ *
+ * Deliberately a closed list rather than a "does this frame live inside
+ * react-dom" heuristic: the latter needs a resolved path for the frame,
+ * which is exactly the thing that may not resolve.
+ */
+export declare const REACT_ELEMENT_CREATION_FRAMES: readonly ["jsxDEV", "jsxDEVImpl", "jsxWithValidation", "jsx", "jsxs", "createElement", "createElementWithValidation"];
+export type OwnerFrameSelection = {
+    readonly ok: true;
+    readonly index: number;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * Index of the frame that is the JSX call site inside the owning component,
+ * or a refusal naming why the stack could not be read that way.
+ */
+export declare function selectOwnerFrame(stack: StackTrace): OwnerFrameSelection;
+//# sourceMappingURL=owner-stack.d.ts.map

package/dist/owner-stack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"owner-stack.d.ts","sourceRoot":"","sources":["../src/owner-stack.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAE7D;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,6BAA6B,uHAQhC,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAC3B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC7C;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAOpD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,mBAAmB,CAsCvE"}

package/dist/owner-stack.js

@@ -0,0 +1,125 @@
+/**
+ * React 19's replacement for `_debugSource`, and the one rule this package
+ * needs in order to read it.
+ *
+ * ## What actually changed between the majors
+ *
+ * Measured directly, in a real Chromium, against React 18.3.1 and 19.2.8
+ * development bundles of the same authored source
+ * (`fixture-apps/react-identity`):
+ *
+ * | fiber field | React 18.3.1 dev | React 19.2.8 dev | either, production |
+ * | --- | --- | --- | --- |
+ * | `_debugSource` | `{ fileName: "src/app.jsx", lineNumber, columnNumber }` | **absent** | absent |
+ * | `_debugStack` | absent | an `Error`, message `react-stack-top-frame` | absent |
+ * | `_debugOwner` | present | present | absent |
+ * | `type.name` | authored | authored | minified |
+ *
+ * So React 19 did not move the source location, it **deleted** it and left
+ * a captured stack in its place. The stack's frames point into *compiled*
+ * output — the bundle the browser actually ran — which is why this path
+ * costs a source-map resolution that React 18's does not, and why the two
+ * mechanisms report different `SourceLocation.reliability` values
+ * (`self-contained` versus `side-artifact-resolved`). That difference is
+ * not cosmetic: one is the application telling us where it came from, the
+ * other is us translating through a file that can be missing or stale.
+ *
+ * ## The rule: drop React's own element-creation frame, and only that
+ *
+ * The captured stack's innermost frame is React's own JSX entry point:
+ *
+ * ```text
+ * Error: react-stack-top-frame
+ *     at exports.jsxDEV (http://…/dev.js:21690:32)
+ *     at PayButton     (http://…/dev.js:21714:62)   <- the site we want
+ *     at Object.react_stack_bottom_frame (…)
+ * ```
+ *
+ * The second frame is the JSX call site inside the owning component, which
+ * is exactly the fact React 18's `_debugSource` carries. Verified against
+ * the fixture: React 18 reports `src/app.jsx:20`, and mapping React 19's
+ * second frame through the bundle's source map lands on `src/app.jsx:20`
+ * as well. `react-fixtures.test.ts` asserts that equality rather than
+ * asserting each major separately, because two independently-written
+ * expectations can both be wrong in the same direction.
+ *
+ * ## Why not `stripInitiatorWrapperFrame`'s positional rule
+ *
+ * `@descryy/runtime-browser`'s initiator capture drops its first frame *by
+ * position*, and argues correctly that its own wrapper is deterministically
+ * innermost because it captured the stack itself. Nothing here captured
+ * this stack — React did — so the same reasoning is not available. Worse,
+ * `createV8StackTraceParser` **omits** frames it cannot parse a
+ * `line:column` from, so "the first frame of the parsed trace" is not
+ * reliably "the first frame of the raw text" either.
+ *
+ * The rule used instead is by name, against a closed list of React's own
+ * element-creation entry points, and it **refuses** when the innermost
+ * frame is not one of them. A refusal here costs a source location; a
+ * positional guess that is off by one costs a confident wrong file and
+ * line, attributed to a component that did not create the element. Rule 2.
+ */
+/**
+ * React's own element-creation entry points, matched against the **last
+ * dotted segment** of a frame's function name so that V8's `exports.jsxDEV`
+ * and a bare `jsxDEV` are the same frame.
+ *
+ * `jsxDEV` / `jsxDEVImpl` are the automatic runtime's development entry;
+ * `jsx` / `jsxs` its production ones (listed for completeness — a
+ * production build has no `_debugStack` to reach this code with);
+ * `createElement` / `createElementWithValidation` the classic runtime's.
+ *
+ * Deliberately a closed list rather than a "does this frame live inside
+ * react-dom" heuristic: the latter needs a resolved path for the frame,
+ * which is exactly the thing that may not resolve.
+ */
+export const REACT_ELEMENT_CREATION_FRAMES = [
+    "jsxDEV",
+    "jsxDEVImpl",
+    "jsxWithValidation",
+    "jsx",
+    "jsxs",
+    "createElement",
+    "createElementWithValidation",
+];
+function lastSegment(functionName) {
+    const parts = functionName.split(".");
+    return parts[parts.length - 1] ?? functionName;
+}
+/**
+ * Index of the frame that is the JSX call site inside the owning component,
+ * or a refusal naming why the stack could not be read that way.
+ */
+export function selectOwnerFrame(stack) {
+    const first = stack.frames[0];
+    if (first === undefined) {
+        return { ok: false, reason: "the captured owner stack parsed to zero frames, so there is no call site in it to read." };
+    }
+    const functionName = first.location.functionName;
+    if (functionName === null) {
+        return {
+            ok: false,
+            reason: "the innermost frame of the captured owner stack has no function name, so it cannot be confirmed to be " +
+                "React's own element-creation frame. Dropping it on position alone would shift every subsequent frame " +
+                "by one and attribute the element to whichever component happened to land there.",
+        };
+    }
+    if (!REACT_ELEMENT_CREATION_FRAMES.includes(lastSegment(functionName))) {
+        return {
+            ok: false,
+            reason: `the innermost frame of the captured owner stack is "${functionName}", which is not one of React's own ` +
+                `element-creation entry points (${REACT_ELEMENT_CREATION_FRAMES.join(", ")}). A minified React build, or a ` +
+                "React version whose owner-stack shape this rule has not been measured against — refused rather than " +
+                "guessed at by position.",
+        };
+    }
+    if (stack.frames.length < 2) {
+        return {
+            ok: false,
+            reason: "the captured owner stack contains React's element-creation frame and nothing after it, so no application " +
+                "call site was recorded (or none of the remaining frames carried a parseable line and column).",
+        };
+    }
+    return { ok: true, index: 1 };
+}
+//# sourceMappingURL=owner-stack.js.map

package/dist/owner-stack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"owner-stack.js","sourceRoot":"","sources":["../src/owner-stack.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAIH;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG;IAC3C,QAAQ;IACR,YAAY;IACZ,mBAAmB;IACnB,KAAK;IACL,MAAM;IACN,eAAe;IACf,6BAA6B;CACrB,CAAC;AAMX,SAAS,WAAW,CAAC,YAAoB;IACvC,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACtC,OAAO,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,YAAY,CAAC;AACjD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAiB;IAChD,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAC9B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,yFAAyF,EAAE,CAAC;IAC1H,CAAC;IAED,MAAM,YAAY,GAAG,KAAK,CAAC,QAAQ,CAAC,YAAY,CAAC;IACjD,IAAI,YAAY,KAAK,IAAI,EAAE,CAAC;QAC1B,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EACJ,wGAAwG;gBACxG,uGAAuG;gBACvG,iFAAiF;SACpF,CAAC;IACJ,CAAC;IAED,IAAI,CAAE,6BAAmD,CAAC,QAAQ,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC;QAC9F,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EACJ,uDAAuD,YAAY,qCAAqC;gBACxG,kCAAkC,6BAA6B,CAAC,IAAI,CAAC,IAAI,CAAC,kCAAkC;gBAC5G,sGAAsG;gBACtG,yBAAyB;SAC5B,CAAC;IACJ,CAAC;IAED,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EACJ,2GAA2G;gBAC3G,+FAA+F;SAClG,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;AAChC,CAAC"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@descryy/runtime-identity-grounding",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Identity grounding: resolves an on-screen DOM element back to the React component that produced it, and to that component's authored file and line. Injects through @descryy/runtime-browser's existing page.addInitScript seam; refuses by name on a production React build rather than guessing.",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.5"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  },
+  "dependencies": {
+    "@descryy/runtime-contracts": "0.2.0",
+    "@descryy/runtime-adapter-typescript": "0.2.0",
+    "@descryy/runtime-browser": "0.2.0",
+    "playwright-core": "^1.62.1"
+  },
+  "devDependencies": {
+    "@descryy/runtime-graph-correlator": "*",
+    "@descryy/runtime-controller": "*"
+  }
+}