@descryy/runtime-identity-grounding 0.3.0 → 0.4.0

package/dist/fiber-probe.js

@@ -2,58 +2,38 @@
  * 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
+ * Read-only, unlike `frontend-initiator-capture.ts` which concedes it
+ * wraps `window.fetch`. This module defines one function on `window` and
+ * reads properties React already put on DOM nodes and fiber objects —
+ * nothing wrapped, nothing patched, no application code path changes shape
+ * (same observation-only guarantee `Collector` states for attach mode).
  *
- * `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 via `page.addInitScript` with a string body, the same mechanism
+ * `frontend-initiator-capture.ts` uses — no transpilation step needed. A
+ * string rather than a typed function because this repo's
+ * `tsconfig.base.json` has no DOM library, so `document`/`window` don't
+ * exist as types here; it keeps the "runs here" vs "runs there" boundary
+ * visible.
  *
- * ## Injected through the existing seam, not a second one
+ * `addInitScript` doesn't reach an already-loaded document — call
+ * `install()` before navigating, or a page reports `probe-not-installed`.
  *
- * `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.
+ * Raw facts only, no decisions: everything returned is a JSON-serialisable
+ * transcript. Deciding what it *means* happens in Node
+ * (`identity-grounding.ts`), unit-testable without a browser. 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.
+ * `__reactFiber$` since React 17, `__reactInternalInstance$` before. Both
+ * checked because both are cheap and a wrong "not React" 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.
+ * Measured present as `__reactFiber$<random>` on React 18.3.1 and 19.2.8;
+ * `__reactInternalInstance$` matches React 16's documented shape but is
+ * NOT covered by this repo's fixtures.
  */
 export const FIBER_KEY_PREFIXES = ["__reactFiber$", "__reactInternalInstance$"];
 export function createIdentityGroundingProbe() {
@@ -67,22 +47,15 @@ export function createIdentityGroundingProbe() {
     };
 }
 /**
- * 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 call side, also a string — **self-invoking**, with the selector
+ * serialised into it rather than passed as an `evaluate` argument. Measured,
+ * not stylistic: a separate `arg` alongside a string body returned
+ * `undefined` here instead of calling the expression with it.
+ * `JSON.stringify` on the selector prevents a quote from breaking out.
  *
- * 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".
+ * The `probe-not-installed` branch lives here, not in the injected script —
+ * a script that never ran can't report that it never ran. This is the only
+ * place that distinction can be drawn.
  */
 function probeCallSource(selector) {
     return `(() => {
@@ -93,34 +66,23 @@ function probeCallSource(selector) {
   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. */
+/** Cap on the key list carried by a `no-fiber` result — a pathological element shouldn't 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
+ * Component detection reads the *type shape*, not `fiber.tag` — the
+ * obvious numeric-tag table (`0 = FunctionComponent`, ...) is a private
+ * React implementation detail with no cross-major guarantee, and a table
+ * wrong on some future React silently misclassifies a component as "not a
+ * component" rather than failing loudly. `fiber.type` is stable and
+ * observable instead: a string is a host element, a function a
+ * function/class component, an object with `render` a `forwardRef`, an
+ * object with `type` a `memo`. `tag` is still reported verbatim for audit.
  *
- * 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.
+ * Everything degrades to null, nothing throws — an unexpected shape yields
+ * `null`, and the whole probe body is wrapped so a read-only observation
+ * can't become a page error the app has to survive.
  */
 function probeScriptSource() {
     return `(() => {
@@ -214,9 +176,8 @@ function probeScriptSource() {
       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.
+        // An invalid selector is the caller's mistake, not a statement
+        // about the page — reported as "matched nothing".
         return { status: "element-not-found", selector: selector };
       }
       if (element === null) return { status: "element-not-found", selector: selector };

package/dist/fiber-probe.js.map

@@ -1 +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"}
+{"version":3,"file":"fiber-probe.js","sourceRoot":"","sources":["../src/fiber-probe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAMH,+FAA+F;AAC/F,MAAM,CAAC,MAAM,0BAA0B,GAAG,2BAA2B,CAAC;AAEtE;;;;;;;;;GASG;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;;;;;;;;;;GAUG;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,yHAAyH;AACzH,MAAM,qBAAqB,GAAG,EAAE,CAAC;AAEjC;;;;;;;;;;;;;;;GAeG;AACH,SAAS,iBAAiB;IACxB,OAAO;+BACsB,IAAI,CAAC,SAAS,CAAC,kBAAkB,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAoFtD,IAAI,CAAC,SAAS,CAAC,0BAA0B,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;mDA4BF,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;MA2BlE,CAAC;AACP,CAAC"}

package/dist/framework-aware-grounder.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Detect, then ground with the matching framework's grounder -- the single
+ * seam both surfaces (`descry-core`'s `playwright-driver.ts`, the desktop's
+ * `browser-drive.ts`) are meant to call instead of hardcoding
+ * `createIdentityGrounder` (React). Composes `createFrameworkDetector`
+ * (`framework-detector.ts`) with `createIdentityGrounder` (React,
+ * `identity-grounder.ts`) and `createVueIdentityGrounder` (Vue,
+ * `vue-identity-grounder.ts`); never defaults to either when detection
+ * fails.
+ *
+ * `install()` installs all three page-side probes -- the detector's and
+ * both frameworks' -- before first navigation, required by
+ * `page.addInitScript`'s contract regardless of which framework the page
+ * turns out to be, since detection cannot run until the document is live.
+ * Installing a probe that never fires costs nothing beyond the one
+ * `addInitScript` registration.
+ *
+ * `ground()` re-detects on every call rather than caching the framework
+ * after the first success: a session's page can navigate to a different
+ * app mid-session (a browser session's grounder is created once and reused
+ * across the whole session, both in `playwright-driver.ts`'s long-lived
+ * session and in the desktop's drive), and a framework cached from page 1
+ * would silently misground page 2 rather than re-deciding honestly.
+ */
+import type { Page } from "playwright-core";
+import type { ElementIdentity } from "./element-identity.ts";
+import { type IdentityGrounderOptions } from "./identity-grounder.ts";
+export interface FrameworkAwareGrounder {
+    /** Installs every page-side probe (detection, React, Vue) into every document this page loads from now on. Call before navigating -- same `addInitScript` contract every probe in this package carries. */
+    install(page: Page): Promise<void>;
+    /** Detects the page's framework, then resolves one on-screen element through that framework's own grounder. Refuses by name (`framework-not-detected`) rather than guessing when neither framework's marker is present. */
+    ground(page: Page, selector: string): Promise<ElementIdentity>;
+}
+export declare function createFrameworkAwareGrounder(options?: IdentityGrounderOptions): FrameworkAwareGrounder;
+//# sourceMappingURL=framework-aware-grounder.d.ts.map

package/dist/framework-aware-grounder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"framework-aware-grounder.d.ts","sourceRoot":"","sources":["../src/framework-aware-grounder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAG7D,OAAO,EAAiD,KAAK,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAGrH,MAAM,WAAW,sBAAsB;IACrC,2MAA2M;IAC3M,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,2NAA2N;IAC3N,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CAChE;AAED,wBAAgB,4BAA4B,CAAC,OAAO,GAAE,uBAA4B,GAAG,sBAAsB,CA6B1G"}

package/dist/framework-aware-grounder.js

@@ -0,0 +1,58 @@
+/**
+ * Detect, then ground with the matching framework's grounder -- the single
+ * seam both surfaces (`descry-core`'s `playwright-driver.ts`, the desktop's
+ * `browser-drive.ts`) are meant to call instead of hardcoding
+ * `createIdentityGrounder` (React). Composes `createFrameworkDetector`
+ * (`framework-detector.ts`) with `createIdentityGrounder` (React,
+ * `identity-grounder.ts`) and `createVueIdentityGrounder` (Vue,
+ * `vue-identity-grounder.ts`); never defaults to either when detection
+ * fails.
+ *
+ * `install()` installs all three page-side probes -- the detector's and
+ * both frameworks' -- before first navigation, required by
+ * `page.addInitScript`'s contract regardless of which framework the page
+ * turns out to be, since detection cannot run until the document is live.
+ * Installing a probe that never fires costs nothing beyond the one
+ * `addInitScript` registration.
+ *
+ * `ground()` re-detects on every call rather than caching the framework
+ * after the first success: a session's page can navigate to a different
+ * app mid-session (a browser session's grounder is created once and reused
+ * across the whole session, both in `playwright-driver.ts`'s long-lived
+ * session and in the desktop's drive), and a framework cached from page 1
+ * would silently misground page 2 rather than re-deciding honestly.
+ */
+import { capabilityFor } from "./element-identity.js";
+import { createFrameworkDetector } from "./framework-detector.js";
+import { createIdentityGrounder } from "./identity-grounder.js";
+import { createVueIdentityGrounder } from "./vue-identity-grounder.js";
+export function createFrameworkAwareGrounder(options = {}) {
+    const detector = createFrameworkDetector();
+    const reactGrounder = createIdentityGrounder(options);
+    const vueGrounder = createVueIdentityGrounder();
+    return {
+        async install(page) {
+            // Order doesn't matter -- addInitScript registrations are independent
+            // and all three must land before the first navigation.
+            await detector.install(page);
+            await reactGrounder.install(page);
+            await vueGrounder.install(page);
+        },
+        async ground(page, selector) {
+            const result = await detector.detect(page);
+            if (result.outcome === "detected") {
+                return result.framework === "react" ? reactGrounder.ground(page, selector) : vueGrounder.ground(page, selector);
+            }
+            return {
+                selector,
+                fiberDistance: 0,
+                outcome: "refused",
+                refusal: "framework-not-detected",
+                reason: result.reason,
+                capability: capabilityFor("unavailable", result.reason),
+                observedTypeName: null,
+            };
+        },
+    };
+}
+//# sourceMappingURL=framework-aware-grounder.js.map

package/dist/framework-aware-grounder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"framework-aware-grounder.js","sourceRoot":"","sources":["../src/framework-aware-grounder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,uBAAuB,EAAiC,MAAM,yBAAyB,CAAC;AACjG,OAAO,EAAE,sBAAsB,EAAuD,MAAM,wBAAwB,CAAC;AACrH,OAAO,EAAE,yBAAyB,EAA4B,MAAM,4BAA4B,CAAC;AASjG,MAAM,UAAU,4BAA4B,CAAC,UAAmC,EAAE;IAChF,MAAM,QAAQ,GAAG,uBAAuB,EAAE,CAAC;IAC3C,MAAM,aAAa,GAAqB,sBAAsB,CAAC,OAAO,CAAC,CAAC;IACxE,MAAM,WAAW,GAAwB,yBAAyB,EAAE,CAAC;IAErE,OAAO;QACL,KAAK,CAAC,OAAO,CAAC,IAAU;YACtB,sEAAsE;YACtE,uDAAuD;YACvD,MAAM,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAC7B,MAAM,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAClC,MAAM,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAClC,CAAC;QACD,KAAK,CAAC,MAAM,CAAC,IAAU,EAAE,QAAgB;YACvC,MAAM,MAAM,GAA6B,MAAM,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACrE,IAAI,MAAM,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;gBAClC,OAAO,MAAM,CAAC,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;YAClH,CAAC;YACD,OAAO;gBACL,QAAQ;gBACR,aAAa,EAAE,CAAC;gBAChB,OAAO,EAAE,SAAS;gBAClB,OAAO,EAAE,wBAAwB;gBACjC,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,UAAU,EAAE,aAAa,CAAC,aAAa,EAAE,MAAM,CAAC,MAAM,CAAC;gBACvD,gBAAgB,EAAE,IAAI;aACvB,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/framework-detector.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Which framework rendered this page, decided by scanning the live document
+ * for the marker each framework's own probe already reads: React's fiber
+ * key (`fiber-probe.ts`'s `FIBER_KEY_PREFIXES`), then Vue's
+ * `__vueParentComponent` (`vue-probe.ts`). Neither found is a named
+ * refusal -- never a default to React.
+ *
+ * This is the one place both surfaces (`descry-core`'s
+ * `packages/mcp/src/browser/playwright-driver.ts` and `descry-desktop`'s
+ * `packages/session/src/pipeline/browser-drive.ts`) are meant to call, so
+ * detection is decided once and the two cannot drift on how they decide.
+ * See `framework-aware-grounder.ts` for the composed grounder that uses
+ * this to pick between `createIdentityGrounder` (React) and
+ * `createVueIdentityGrounder` (Vue).
+ *
+ * Page-wide, not selector-scoped, deliberately: the element a caller wants
+ * grounded may sit outside the framework's own mount root (a static
+ * wrapper around an app), and a selector-scoped scan would misreport "not
+ * React" for a real React page just because the queried node happens to sit
+ * outside it. Scanning the whole document answers the honest, broader
+ * question -- "did this framework render anything on this page at all" --
+ * which is what deciding *which grounder to use* needs; the per-selector
+ * probes answer the narrower one ("did it render *this* element") once a
+ * grounder has already been chosen.
+ */
+import type { Page } from "playwright-core";
+/** The single global this installs. One name, one function, no other footprint on the page -- same discipline as `fiber-probe.ts`'s and `vue-probe.ts`'s own bindings. */
+export declare const FRAMEWORK_DETECTION_BINDING = "__descryFrameworkDetection";
+/** Checked in this order, always: React's fiber marker, then Vue's component marker. Never the reverse, and never a default. */
+export declare const DETECTABLE_FRAMEWORKS: readonly ["react", "vue"];
+export type DetectableFramework = (typeof DETECTABLE_FRAMEWORKS)[number];
+export type FrameworkDetectionResult = {
+    readonly outcome: "detected";
+    readonly framework: DetectableFramework;
+} | {
+    readonly outcome: "refused";
+    readonly reason: string;
+};
+export interface FrameworkDetector {
+    /** Installs the page-side reader into every document this page loads from now on. Call before navigating -- a page navigated first reports a `probe-not-installed`-shaped refusal, same contract `fiber-probe.ts`'s `install` documents. */
+    install(page: Page): Promise<void>;
+    /** Scans the page's current document and names which framework rendered it, or refuses by name. Never throws for a routine unavailability. */
+    detect(page: Page): Promise<FrameworkDetectionResult>;
+}
+export declare function createFrameworkDetector(): FrameworkDetector;
+//# sourceMappingURL=framework-detector.d.ts.map

package/dist/framework-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"framework-detector.d.ts","sourceRoot":"","sources":["../src/framework-detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAI5C,0KAA0K;AAC1K,eAAO,MAAM,2BAA2B,+BAA+B,CAAC;AAExE,gIAAgI;AAChI,eAAO,MAAM,qBAAqB,2BAA4B,CAAC;AAC/D,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzE,MAAM,MAAM,wBAAwB,GAChC;IAAE,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,mBAAmB,CAAA;CAAE,GACzE;IAAE,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7D,MAAM,WAAW,iBAAiB;IAChC,4OAA4O;IAC5O,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,8IAA8I;IAC9I,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAC;CACvD;AAED,wBAAgB,uBAAuB,IAAI,iBAAiB,CAS3D"}

package/dist/framework-detector.js

@@ -0,0 +1,89 @@
+/**
+ * Which framework rendered this page, decided by scanning the live document
+ * for the marker each framework's own probe already reads: React's fiber
+ * key (`fiber-probe.ts`'s `FIBER_KEY_PREFIXES`), then Vue's
+ * `__vueParentComponent` (`vue-probe.ts`). Neither found is a named
+ * refusal -- never a default to React.
+ *
+ * This is the one place both surfaces (`descry-core`'s
+ * `packages/mcp/src/browser/playwright-driver.ts` and `descry-desktop`'s
+ * `packages/session/src/pipeline/browser-drive.ts`) are meant to call, so
+ * detection is decided once and the two cannot drift on how they decide.
+ * See `framework-aware-grounder.ts` for the composed grounder that uses
+ * this to pick between `createIdentityGrounder` (React) and
+ * `createVueIdentityGrounder` (Vue).
+ *
+ * Page-wide, not selector-scoped, deliberately: the element a caller wants
+ * grounded may sit outside the framework's own mount root (a static
+ * wrapper around an app), and a selector-scoped scan would misreport "not
+ * React" for a real React page just because the queried node happens to sit
+ * outside it. Scanning the whole document answers the honest, broader
+ * question -- "did this framework render anything on this page at all" --
+ * which is what deciding *which grounder to use* needs; the per-selector
+ * probes answer the narrower one ("did it render *this* element") once a
+ * grounder has already been chosen.
+ */
+import { FIBER_KEY_PREFIXES } from "./fiber-probe.js";
+/** The single global this installs. One name, one function, no other footprint on the page -- same discipline as `fiber-probe.ts`'s and `vue-probe.ts`'s own bindings. */
+export const FRAMEWORK_DETECTION_BINDING = "__descryFrameworkDetection";
+/** Checked in this order, always: React's fiber marker, then Vue's component marker. Never the reverse, and never a default. */
+export const DETECTABLE_FRAMEWORKS = ["react", "vue"];
+export function createFrameworkDetector() {
+    return {
+        async install(page) {
+            await page.addInitScript({ content: probeScriptSource() });
+        },
+        detect(page) {
+            return page.evaluate(callSource());
+        },
+    };
+}
+/** Self-invoking, no arguments needed -- unlike the per-element probes there is no selector to serialise in. The `probe-not-installed` branch lives here, not in the injected script, for the same reason `fiber-probe.ts`'s `probeCallSource` gives: a script that never ran cannot report that it never ran. */
+function callSource() {
+    return `(() => {
+  const detection = window[${JSON.stringify(FRAMEWORK_DETECTION_BINDING)}];
+  if (detection === undefined || typeof detection.detect !== "function") {
+    return {
+      outcome: "refused",
+      reason: "the framework-detection probe was never installed (install() must run before the page's first navigation)",
+    };
+  }
+  return detection.detect();
+})()`;
+}
+function probeScriptSource() {
+    return `(() => {
+  const FIBER_KEY_PREFIXES = ${JSON.stringify(FIBER_KEY_PREFIXES)};
+
+  function hasReactFiberKey(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 true;
+      }
+    }
+    return false;
+  }
+
+  function hasVueMarker(element) {
+    return element.__vueParentComponent !== undefined && element.__vueParentComponent !== null;
+  }
+
+  window[${JSON.stringify(FRAMEWORK_DETECTION_BINDING)}] = {
+    detect: function () {
+      const all = document.querySelectorAll("*");
+      for (let i = 0; i < all.length; i++) {
+        if (hasReactFiberKey(all[i])) return { outcome: "detected", framework: "react" };
+      }
+      for (let i = 0; i < all.length; i++) {
+        if (hasVueMarker(all[i])) return { outcome: "detected", framework: "vue" };
+      }
+      return {
+        outcome: "refused",
+        reason: "neither a React fiber key nor a Vue __vueParentComponent marker was found anywhere in the document",
+      };
+    },
+  };
+})();`;
+}
+//# sourceMappingURL=framework-detector.js.map

package/dist/framework-detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"framework-detector.js","sourceRoot":"","sources":["../src/framework-detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAEtD,0KAA0K;AAC1K,MAAM,CAAC,MAAM,2BAA2B,GAAG,4BAA4B,CAAC;AAExE,gIAAgI;AAChI,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,OAAO,EAAE,KAAK,CAAU,CAAC;AAc/D,MAAM,UAAU,uBAAuB;IACrC,OAAO;QACL,KAAK,CAAC,OAAO,CAAC,IAAU;YACtB,MAAM,IAAI,CAAC,aAAa,CAAC,EAAE,OAAO,EAAE,iBAAiB,EAAE,EAAE,CAAC,CAAC;QAC7D,CAAC;QACD,MAAM,CAAC,IAAU;YACf,OAAO,IAAI,CAAC,QAAQ,CAA2B,UAAU,EAAE,CAAC,CAAC;QAC/D,CAAC;KACF,CAAC;AACJ,CAAC;AAED,kTAAkT;AAClT,SAAS,UAAU;IACjB,OAAO;6BACoB,IAAI,CAAC,SAAS,CAAC,2BAA2B,CAAC;;;;;;;;KAQnE,CAAC;AACN,CAAC;AAED,SAAS,iBAAiB;IACxB,OAAO;+BACsB,IAAI,CAAC,SAAS,CAAC,kBAAkB,CAAC;;;;;;;;;;;;;;;;WAgBtD,IAAI,CAAC,SAAS,CAAC,2BAA2B,CAAC;;;;;;;;;;;;;;;MAehD,CAAC;AACP,CAAC"}

package/dist/graph-join.d.ts

@@ -1,61 +1,30 @@
 /**
- * The join to `descry-core`'s graph — as a **hand-off**, not a second
- * resolver.
+ * The join to `descry-core`'s graph — a **hand-off**, not a second
+ * resolver. `resolveSymbolNode` already does the whole job of turning
+ * `{ file, symbolName, line }` into a `FUNCTION`/`CLASS` node — refusing
+ * ambiguity, checking the line against the node's range, translating path
+ * languages, requiring `repo` since there's no honest default. This
+ * function's entire contract: hand it exactly that input, or hand it
+ * nothing.
  *
- * `@descryy/runtime-graph-correlator`'s `resolveSymbolNode` already does the
- * whole job of turning `{ file, symbolName, line }` into a `FUNCTION`/
- * `CLASS` node, and everything hard about that job is in the parts this
- * function must not duplicate: refusing ambiguity instead of ranking
- * candidates, checking the claimed line against the node's own range and
- * reporting `line-mismatch` distinctly, translating between the absolute /
- * repo-relative / relative-to-launch-cwd path languages, and requiring
- * `repo` because `FUNCTION` is repo-scoped and there is no honest default.
- * A copy of any of that here would be a copy that drifts.
+ * No new node type, no new edge type — resolves to a `FUNCTION`/`CLASS`
+ * node an adapter already produced. `descry-core`'s frozen 15/15 vocabulary
+ * is untouched.
  *
- * So this function's entire contract is: hand `resolveSymbolNode` exactly
- * the input it asks for, or hand it nothing.
- *
- * ## No new node type, no new edge type
- *
- * The component resolves to a `FUNCTION` or `CLASS` node that an adapter
- * already produced — `descry-core`'s frozen 15 node types and 15 edge types
- * are untouched. There is no `COMPONENT_INSTANCE`, no `RENDERS` edge, and
- * nothing here asks for one. (`COMPONENT` is already one of the 15, and a
- * React component that an adapter emitted as one is found by the same
- * name+file lookup.)
- *
- * ## Why a compiled location is withheld rather than passed through
- *
- * `resolveSymbolNode` would take a bundle path quite happily and report
- * `not-found` for it, which reads to a consumer as *"that component is not
- * in the graph"* — the exact misleading refusal `symbol.ts`'s own header
- * describes and fixed for absolute paths. A React 19 answer with
- * `authoredSource: false` names `dist/dev.js`, a file no adapter ever
- * indexed and never will. Withholding it keeps the honest statement —
- * *"we know the component, we could not reach authored source"* — inside
- * `ElementIdentity`, where the capability status explains it, instead of
- * laundering it into a graph miss.
+ * A compiled location is withheld rather than passed through:
+ * `resolveSymbolNode` would report `not-found` for a bundle path, reading
+ * as "not in the graph" — the exact misleading refusal `symbol.ts` fixed
+ * for absolute paths. Withholding it keeps the honest statement ("we know
+ * the component, couldn't reach authored source") inside `ElementIdentity`,
+ * not laundered into a graph miss.
  */
 import type { ElementIdentity } from "./element-identity.ts";
-/**
- * Structurally `resolveSymbolNode`'s own `location` parameter. Deliberately
- * declared with `line` optional rather than nullable, because that is the
- * shape that function accepts; `graph-join.test.ts` asserts the
- * compatibility against the real signature at compile time, so a change on
- * either side breaks the build rather than being discovered at runtime.
- */
+/** Structurally `resolveSymbolNode`'s own `location` parameter — `line` optional, not nullable, matching that function's shape. `graph-join.test.ts` asserts the compatibility at compile time. */
 export interface GraphSymbolLocation {
     readonly file: string;
     readonly symbolName: string;
     readonly line?: number;
 }
-/**
- * The graph lookup this identity supports, or `null` when it supports none.
- *
- * `null` for every outcome except a `grounded` one that reached authored
- * source with a real file — including `component-only`, which knows the
- * component's name and nothing about where it lives, and including a
- * `grounded` answer whose location is compiled output.
- */
+/** The graph lookup this identity supports, or `null` when it supports none — only a `grounded` outcome with authored source and a real file. */
 export declare function symbolLocationForGraph(identity: ElementIdentity): GraphSymbolLocation | null;
 //# sourceMappingURL=graph-join.d.ts.map

package/dist/graph-join.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph-join.d.ts","sourceRoot":"","sources":["../src/graph-join.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,eAAe,GAAG,mBAAmB,GAAG,IAAI,CAU5F"}
+{"version":3,"file":"graph-join.d.ts","sourceRoot":"","sources":["../src/graph-join.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,mMAAmM;AACnM,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,iJAAiJ;AACjJ,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,eAAe,GAAG,mBAAmB,GAAG,IAAI,CAU5F"}

package/dist/graph-join.js

@@ -1,49 +1,24 @@
 /**
- * The join to `descry-core`'s graph — as a **hand-off**, not a second
- * resolver.
+ * The join to `descry-core`'s graph — a **hand-off**, not a second
+ * resolver. `resolveSymbolNode` already does the whole job of turning
+ * `{ file, symbolName, line }` into a `FUNCTION`/`CLASS` node — refusing
+ * ambiguity, checking the line against the node's range, translating path
+ * languages, requiring `repo` since there's no honest default. This
+ * function's entire contract: hand it exactly that input, or hand it
+ * nothing.
  *
- * `@descryy/runtime-graph-correlator`'s `resolveSymbolNode` already does the
- * whole job of turning `{ file, symbolName, line }` into a `FUNCTION`/
- * `CLASS` node, and everything hard about that job is in the parts this
- * function must not duplicate: refusing ambiguity instead of ranking
- * candidates, checking the claimed line against the node's own range and
- * reporting `line-mismatch` distinctly, translating between the absolute /
- * repo-relative / relative-to-launch-cwd path languages, and requiring
- * `repo` because `FUNCTION` is repo-scoped and there is no honest default.
- * A copy of any of that here would be a copy that drifts.
+ * No new node type, no new edge type — resolves to a `FUNCTION`/`CLASS`
+ * node an adapter already produced. `descry-core`'s frozen 15/15 vocabulary
+ * is untouched.
  *
- * So this function's entire contract is: hand `resolveSymbolNode` exactly
- * the input it asks for, or hand it nothing.
- *
- * ## No new node type, no new edge type
- *
- * The component resolves to a `FUNCTION` or `CLASS` node that an adapter
- * already produced — `descry-core`'s frozen 15 node types and 15 edge types
- * are untouched. There is no `COMPONENT_INSTANCE`, no `RENDERS` edge, and
- * nothing here asks for one. (`COMPONENT` is already one of the 15, and a
- * React component that an adapter emitted as one is found by the same
- * name+file lookup.)
- *
- * ## Why a compiled location is withheld rather than passed through
- *
- * `resolveSymbolNode` would take a bundle path quite happily and report
- * `not-found` for it, which reads to a consumer as *"that component is not
- * in the graph"* — the exact misleading refusal `symbol.ts`'s own header
- * describes and fixed for absolute paths. A React 19 answer with
- * `authoredSource: false` names `dist/dev.js`, a file no adapter ever
- * indexed and never will. Withholding it keeps the honest statement —
- * *"we know the component, we could not reach authored source"* — inside
- * `ElementIdentity`, where the capability status explains it, instead of
- * laundering it into a graph miss.
- */
-/**
- * The graph lookup this identity supports, or `null` when it supports none.
- *
- * `null` for every outcome except a `grounded` one that reached authored
- * source with a real file — including `component-only`, which knows the
- * component's name and nothing about where it lives, and including a
- * `grounded` answer whose location is compiled output.
+ * A compiled location is withheld rather than passed through:
+ * `resolveSymbolNode` would report `not-found` for a bundle path, reading
+ * as "not in the graph" — the exact misleading refusal `symbol.ts` fixed
+ * for absolute paths. Withholding it keeps the honest statement ("we know
+ * the component, couldn't reach authored source") inside `ElementIdentity`,
+ * not laundered into a graph miss.
  */
+/** The graph lookup this identity supports, or `null` when it supports none — only a `grounded` outcome with authored source and a real file. */
 export function symbolLocationForGraph(identity) {
     if (identity.outcome !== "grounded")
         return null;

package/dist/graph-join.js.map

@@ -1 +1 @@
-{"version":3,"file":"graph-join.js","sourceRoot":"","sources":["../src/graph-join.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAiBH;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CAAC,QAAyB;IAC9D,IAAI,QAAQ,CAAC,OAAO,KAAK,UAAU;QAAE,OAAO,IAAI,CAAC;IACjD,IAAI,CAAC,QAAQ,CAAC,cAAc;QAAE,OAAO,IAAI,CAAC;IAE1C,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,QAAQ,CAAC,cAAc,CAAC;IAC/C,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAE/B,OAAO,IAAI,KAAK,IAAI;QAClB,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAE;QAC/C,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC;AAC1D,CAAC"}
+{"version":3,"file":"graph-join.js","sourceRoot":"","sources":["../src/graph-join.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAWH,iJAAiJ;AACjJ,MAAM,UAAU,sBAAsB,CAAC,QAAyB;IAC9D,IAAI,QAAQ,CAAC,OAAO,KAAK,UAAU;QAAE,OAAO,IAAI,CAAC;IACjD,IAAI,CAAC,QAAQ,CAAC,cAAc;QAAE,OAAO,IAAI,CAAC;IAE1C,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,QAAQ,CAAC,cAAc,CAAC;IAC/C,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAE/B,OAAO,IAAI,KAAK,IAAI;QAClB,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAE;QAC/C,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC;AAC1D,CAAC"}