react-native-tapline 1.5.0 → 1.6.1

package/dist/place.d.ts

@@ -0,0 +1,23 @@
+import type { PlaceState } from './types';
+export { routePattern } from './placekey';
+export type { PlaceState } from './types';
+/**
+ * AGENT-TOOLS 1.13 §18.1 and §18.11. Where the app is, as a route key: pattern names, the selected
+ * tab and what lies on top. Never a param's value and never text from the screen.
+ */
+/** The wire form of a place: the key and when it was read. Answers the `place` request and is the `place` event's data. */
+export interface PlaceData extends PlaceState {
+    seenAt: number;
+}
+/** The place now; null when the app has no React roots yet. A walk that fails answers null, never throws. */
+export declare function currentPlace(): PlaceState | null;
+/** The `place` request: no router (or no roots) gives an empty route. */
+export declare function placeData(now?: () => number): PlaceData;
+/**
+ * Sends a `place` event now and again whenever the route, the tab or the layer changes, after the commit
+ * that changed it (one event per burst of commits, none on a repeat). Returns a function that stops it.
+ */
+export declare function startPlaceEvents(options?: {
+    debounceMs?: number;
+    now?: () => number;
+}): () => void;

package/dist/place.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.routePattern = void 0;
+exports.currentPlace = currentPlace;
+exports.placeData = placeData;
+exports.startPlaceEvents = startPlaceEvents;
+const alerts_1 = require("./alerts");
+const events_1 = require("./events");
+const inspect_1 = require("./inspect");
+const placekey_1 = require("./placekey");
+const register_1 = require("./register");
+var placekey_2 = require("./placekey");
+Object.defineProperty(exports, "routePattern", { enumerable: true, get: function () { return placekey_2.routePattern; } });
+/** After a commit the app is given this long to finish committing before the place is read (one read per burst). */
+const DEBOUNCE_MS = 40;
+/** The place now; null when the app has no React roots yet. A walk that fails answers null, never throws. */
+function currentPlace() {
+    try {
+        const parts = (0, inspect_1.placeParts)();
+        return parts === null ? null : (0, placekey_1.placeFrom)(parts);
+    }
+    catch {
+        return null;
+    }
+}
+/** The `place` request: no router (or no roots) gives an empty route. */
+function placeData(now = Date.now) {
+    return { ...(currentPlace() ?? { route: [] }), seenAt: now() };
+}
+/**
+ * Sends a `place` event now and again whenever the route, the tab or the layer changes, after the commit
+ * that changed it (one event per burst of commits, none on a repeat). Returns a function that stops it.
+ */
+function startPlaceEvents(options = {}) {
+    const wait = options.debounceMs ?? DEBOUNCE_MS;
+    const now = options.now ?? Date.now;
+    let last = null;
+    let timer;
+    let stopped = false;
+    const check = () => {
+        timer = undefined;
+        if (stopped)
+            return;
+        const place = currentPlace() ?? { route: [] };
+        if (last !== null && (0, placekey_1.samePlace)(last, place))
+            return;
+        last = place;
+        (0, events_1.emitEvent)('place', { ...place, seenAt: now() });
+    };
+    const schedule = () => {
+        if (stopped || timer !== undefined)
+            return;
+        timer = setTimeout(check, wait);
+    };
+    const stopCommits = (0, register_1.onCommit)(schedule);
+    const stopAlerts = (0, alerts_1.onAlertsChange)(schedule);
+    check();
+    return () => {
+        stopped = true;
+        if (timer !== undefined)
+            clearTimeout(timer);
+        stopCommits();
+        stopAlerts();
+    };
+}
+//# sourceMappingURL=place.js.map

package/dist/place.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"place.js","sourceRoot":"","sources":["../src/place.ts"],"names":[],"mappings":";;;AAwBA,oCAOC;AAGD,8BAEC;AAMD,4CA6BC;AAvED,qCAA0C;AAC1C,qCAAqC;AACrC,uCAAuC;AACvC,yCAAkD;AAClD,yCAAsC;AAGtC,uCAA0C;AAAjC,wGAAA,YAAY,OAAA;AAarB,oHAAoH;AACpH,MAAM,WAAW,GAAG,EAAE,CAAC;AAEvB,6GAA6G;AAC7G,SAAgB,YAAY;IAC1B,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,IAAA,oBAAU,GAAE,CAAC;QAC3B,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAA,oBAAS,EAAC,KAAK,CAAC,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,yEAAyE;AACzE,SAAgB,SAAS,CAAC,MAAoB,IAAI,CAAC,GAAG;IACpD,OAAO,EAAE,GAAG,CAAC,YAAY,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC;AACjE,CAAC;AAED;;;GAGG;AACH,SAAgB,gBAAgB,CAAC,UAAuD,EAAE;IACxF,MAAM,IAAI,GAAG,OAAO,CAAC,UAAU,IAAI,WAAW,CAAC;IAC/C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;IACpC,IAAI,IAAI,GAAsB,IAAI,CAAC;IACnC,IAAI,KAAgD,CAAC;IACrD,IAAI,OAAO,GAAG,KAAK,CAAC;IAEpB,MAAM,KAAK,GAAG,GAAS,EAAE;QACvB,KAAK,GAAG,SAAS,CAAC;QAClB,IAAI,OAAO;YAAE,OAAO;QACpB,MAAM,KAAK,GAAG,YAAY,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;QAC9C,IAAI,IAAI,KAAK,IAAI,IAAI,IAAA,oBAAS,EAAC,IAAI,EAAE,KAAK,CAAC;YAAE,OAAO;QACpD,IAAI,GAAG,KAAK,CAAC;QACb,IAAA,kBAAS,EAAC,OAAO,EAAE,EAAE,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;IAClD,CAAC,CAAC;IACF,MAAM,QAAQ,GAAG,GAAS,EAAE;QAC1B,IAAI,OAAO,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO;QAC3C,KAAK,GAAG,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAClC,CAAC,CAAC;IAEF,MAAM,WAAW,GAAG,IAAA,mBAAQ,EAAC,QAAQ,CAAC,CAAC;IACvC,MAAM,UAAU,GAAG,IAAA,uBAAc,EAAC,QAAQ,CAAC,CAAC;IAC5C,KAAK,EAAE,CAAC;IACR,OAAO,GAAG,EAAE;QACV,OAAO,GAAG,IAAI,CAAC;QACf,IAAI,KAAK,KAAK,SAAS;YAAE,YAAY,CAAC,KAAK,CAAC,CAAC;QAC7C,WAAW,EAAE,CAAC;QACd,UAAU,EAAE,CAAC;IACf,CAAC,CAAC;AACJ,CAAC"}

package/dist/placekey.d.ts

@@ -0,0 +1,29 @@
+import { type Fiber } from './fiber';
+import type { RouteFound, TabFound } from './inspect';
+import { type PlaceState } from './types';
+/**
+ * AGENT-TOOLS 1.13 §18.1: a place as a route key. Pure: it reads what the tree walk found and
+ * nothing else, so `tree` and the `place` event agree. Never a param's value, never screen text.
+ */
+/** What a walk of the tree found that a place is made of. */
+export interface PlaceParts {
+    routes: RouteFound[];
+    tabs: TabFound[];
+    /** The topmost open `Modal`'s host fiber, when one is open. */
+    modal: Fiber | null;
+}
+/** Splits each route name on "/" so "trips/[id]" and ["trips","[id]"] agree (answer 12); empty pieces go. */
+export declare function routePattern(names: string[]): string[];
+/**
+ * A native tab's route name from its `screenKey`. React Navigation keys are `<route name>-<21-character id>`, so the
+ * id is cut only when it is there; a key such as "home-tab" is a name with no id (and a name may hold a hyphen).
+ */
+export declare function tabNameFromKey(key: string): string;
+/**
+ * Whether a piece of a place looks like a value (an id, a number, a UUID, long hex) and not a name. A place holds
+ * patterns, never values (AGENT-TOOLS 1.13 §18.1). The host applies the same rule.
+ */
+export declare function looksLikeValue(piece: string): boolean;
+export declare function placeFrom(parts: PlaceParts): PlaceState;
+/** Whether two places are the same key. */
+export declare function samePlace(a: PlaceState | null, b: PlaceState | null): boolean;

package/dist/placekey.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.routePattern = routePattern;
+exports.tabNameFromKey = tabNameFromKey;
+exports.looksLikeValue = looksLikeValue;
+exports.placeFrom = placeFrom;
+exports.samePlace = samePlace;
+const alerts_1 = require("./alerts");
+const fiber_1 = require("./fiber");
+const types_1 = require("./types");
+/** Splits each route name on "/" so "trips/[id]" and ["trips","[id]"] agree (answer 12); empty pieces go. */
+function routePattern(names) {
+    const out = [];
+    for (const name of names) {
+        for (const piece of name.split('/'))
+            if (piece !== '')
+                out.push(piece);
+    }
+    return out;
+}
+const SHEET_PRESENTATIONS = new Set(['formSheet', 'pageSheet', 'sheet']);
+/** The deepest focused route, the last on ties (the same rule as `currentRoute`). */
+function focusedRoute(routes) {
+    let best = null;
+    for (const route of routes) {
+        if (!route.focused)
+            continue;
+        if (best === null || route.chain.length >= best.chain.length)
+            best = route;
+    }
+    return best;
+}
+/**
+ * A native tab's route name from its `screenKey`. React Navigation keys are `<route name>-<21-character id>`, so the
+ * id is cut only when it is there; a key such as "home-tab" is a name with no id (and a name may hold a hyphen).
+ */
+function tabNameFromKey(key) {
+    const match = /^(.+)-[A-Za-z0-9_-]{21}$/.exec(key);
+    return match?.[1] ?? key;
+}
+/** Whether `chain` starts with `prefix`. */
+function startsWith(chain, prefix) {
+    return prefix.length <= chain.length && prefix.every((name, i) => chain[i] === name);
+}
+/** The root `testID` of a bare Modal's content, or undefined. */
+function modalName(modal) {
+    const root = (0, fiber_1.firstHostChild)(modal);
+    const id = root ? (0, fiber_1.propsOf)(root).testID : undefined;
+    return typeof id === 'string' && id !== '' ? id : undefined;
+}
+/** `/` and `:` never appear in a layer name, so a key stays one piece. */
+function plain(name) {
+    return name.replace(/[:/]/g, '_');
+}
+/**
+ * Whether a piece of a place looks like a value (an id, a number, a UUID, long hex) and not a name. A place holds
+ * patterns, never values (AGENT-TOOLS 1.13 §18.1). The host applies the same rule.
+ */
+function looksLikeValue(piece) {
+    return (/^\d+$/.test(piece) ||
+        /\d{4,}/.test(piece) ||
+        /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i.test(piece) ||
+        /[0-9a-f]{16,}/i.test(piece));
+}
+/** A layer: its kind and, when the name isn't a value, its name. */
+function layerOf(kind, name) {
+    return name === undefined || looksLikeValue(name) ? kind : `${kind}:${plain(name)}`;
+}
+/** Whether `fiber` lies inside `outer` (either copy of it). */
+function inside(fiber, outer) {
+    for (let up = fiber.return; up; up = up.return) {
+        if (up === outer || up === outer.alternate)
+            return true;
+    }
+    return false;
+}
+/**
+ * Whether a bare Modal lies above a presented route: the Modal is inside that route's screen (opened from it) and the
+ * route is not inside the Modal. When the order can't be told, the route stays the layer, as before.
+ */
+function modalAbove(modal, route) {
+    return route.fiber !== undefined && inside(modal, route.fiber) && !inside(route.fiber, modal);
+}
+function placeFrom(parts) {
+    const current = focusedRoute(parts.routes);
+    const chain = current ? current.chain : [];
+    const route = routePattern(chain);
+    // A route piece that looks like a value can't be a pattern: no route, and the host falls back to its signature.
+    const place = { route: route.some(looksLikeValue) ? [] : route };
+    const onPath = parts.routes.filter((route) => route.focused && startsWith(chain, route.chain));
+    // The selected tab: a tab navigator's selected route, else a native tab bar's selected tab (by its key, never its title).
+    for (const route of onPath) {
+        let type;
+        try {
+            const state = route.navigation.getState?.();
+            type = (0, types_1.isRecord)(state) ? state.type : undefined;
+        }
+        catch {
+            type = undefined;
+        }
+        if (type === 'tab') {
+            place.tab = route.name;
+            break;
+        }
+    }
+    if (place.tab === undefined) {
+        const selected = parts.tabs.find((tab) => tab.selected && tab.screenKey !== null);
+        if (selected?.screenKey)
+            place.tab = tabNameFromKey(selected.screenKey);
+    }
+    // What lies on top: an alert, else a modal or sheet (a navigation route's name, else a bare Modal's root testID).
+    if ((0, alerts_1.openAlerts)().length > 0) {
+        place.layer = 'alert';
+    }
+    else {
+        const presented = [...onPath].reverse().find((route) => route.presentation !== undefined);
+        if (presented?.presentation !== undefined && !(parts.modal && modalAbove(parts.modal, presented))) {
+            place.layer = layerOf(SHEET_PRESENTATIONS.has(presented.presentation) ? 'sheet' : 'modal', presented.name);
+        }
+        else if (parts.modal) {
+            place.layer = layerOf('modal', modalName(parts.modal));
+        }
+    }
+    if (place.tab !== undefined && looksLikeValue(place.tab))
+        delete place.tab;
+    return place;
+}
+/** Whether two places are the same key. */
+function samePlace(a, b) {
+    if (a === null || b === null)
+        return a === b;
+    return a.tab === b.tab && a.layer === b.layer && a.route.length === b.route.length && a.route.every((name, i) => name === b.route[i]);
+}
+//# sourceMappingURL=placekey.js.map

package/dist/placekey.js.map

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

package/dist/routetree.d.ts

@@ -0,0 +1,27 @@
+/**
+ * AGENT-TOOLS 1.13 §18.1 ("Known before any visit"): the places an app has, listed from its own route tree. Expo Router's
+ * store is an internal API, so it is read behind a guard and any failure answers `source: "none"` (plan answer 21).
+ * Values of params never appear here, only their names.
+ */
+export interface KnownPlace {
+    route: string[];
+    /** `<scheme>://<path>`, with `[id]` where a param goes; absent when the app has no scheme or the screen has no path. */
+    link?: string;
+    /** Param names such as "id"; values never. */
+    params: string[];
+}
+export interface KnownPlaces {
+    source: 'expo-router' | 'react-navigation' | 'none';
+    places: KnownPlace[];
+}
+/**
+ * The places in an Expo Router route tree (its `routeNode`): every leaf route, keyed by the layout and route names down to
+ * it. Exported for tests; the shape is read defensively, since it is Expo Router's own.
+ */
+export declare function placesFromExpoTree(root: unknown, scheme: string | undefined): KnownPlace[];
+/** A custom scheme beats an `https` prefix (the app opens from it directly); wildcard prefixes can't be used. */
+export declare function pickPrefix(prefixes: unknown): string | undefined;
+/** The places in a React Navigation `linking.config`: each leaf screen, keyed by the screen names down to it. Exported for tests. */
+export declare function placesFromLinking(linking: unknown): KnownPlace[];
+/** The `places` request: what the app's own route tree says it has, before any visit. Never throws. */
+export declare function knownPlaces(): KnownPlaces;

package/dist/routetree.js

@@ -0,0 +1,216 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.placesFromExpoTree = placesFromExpoTree;
+exports.pickPrefix = pickPrefix;
+exports.placesFromLinking = placesFromLinking;
+exports.knownPlaces = knownPlaces;
+const appinfo_1 = require("./appinfo");
+const fiber_1 = require("./fiber");
+const placekey_1 = require("./placekey");
+const register_1 = require("./register");
+const types_1 = require("./types");
+/** Never go deeper than this: a route tree is a few levels; a cycle must not hang the app. */
+const MAX_DEPTH = 12;
+const MAX_PLACES = 500;
+/* -------------------------------------------------------------------------- */
+/* Expo Router                                                                 */
+/* -------------------------------------------------------------------------- */
+const EXPO_PARAM = /^\[(?:\.\.\.)?([^\]]+)\]$/;
+/** A group segment such as "(tabs)": part of the route key, not of the path. */
+function isGroup(segment) {
+    return /^\(.*\)$/.test(segment);
+}
+/** Special files that aren't places a person navigates to: `+not-found`, `_sitemap` and the like. */
+function isSpecial(name) {
+    return name.startsWith('+') || name.startsWith('_');
+}
+/**
+ * The places in an Expo Router route tree (its `routeNode`): every leaf route, keyed by the layout and route names down to
+ * it. Exported for tests; the shape is read defensively, since it is Expo Router's own.
+ */
+function placesFromExpoTree(root, scheme) {
+    const places = [];
+    const visit = (node, names, depth) => {
+        if (!(0, types_1.isRecord)(node) || depth > MAX_DEPTH || places.length >= MAX_PLACES)
+            return;
+        const name = typeof node.route === 'string' ? node.route : '';
+        if (isSpecial(name) || node.type === 'api' || node.type === 'redirect' || node.type === 'rewrite')
+            return;
+        const here = name === '' ? names : [...names, name];
+        const children = Array.isArray(node.children) ? node.children : [];
+        if (children.length > 0) {
+            for (const child of children)
+                visit(child, here, depth + 1);
+            return;
+        }
+        if (node.type === 'layout' || here.length === 0)
+            return; // a layout with no screens is not a place
+        const route = (0, placekey_1.routePattern)(here);
+        const params = [];
+        for (const segment of route) {
+            const match = EXPO_PARAM.exec(segment);
+            if (match?.[1] !== undefined && !params.includes(match[1]))
+                params.push(match[1]);
+        }
+        const path = route.filter((segment) => !isGroup(segment) && segment !== 'index');
+        const place = { route, params };
+        if (scheme !== undefined)
+            place.link = `${scheme}://${path.join('/')}`;
+        places.push(place);
+    };
+    visit(root, [], 0);
+    return places;
+}
+/**
+ * Expo Router 58: the route tree is `routerConfig.routeNode`, the value of `RouterConfigContext`'s provider, which sits
+ * above the navigation container. Found through the fibers, the way the linking prop is.
+ */
+function findRouterConfigNode() {
+    return findInFibers((props) => {
+        const value = props.value;
+        return (0, types_1.isRecord)(value) && (0, types_1.isRecord)(value.routeNode) && Array.isArray(value.routeNode.children) ? value.routeNode : undefined;
+    });
+}
+/** Expo Router 55: `routeNode` from its store, or null. Any failure (not installed, another version) is null. */
+function expoStoreRouteNode() {
+    try {
+        // The `.js` matters: the package's exports map refuses an extensionless deep path.
+        const loaded = require('expo-router/build/global-state/router-store.js');
+        const store = (0, types_1.isRecord)(loaded) ? loaded.store : undefined;
+        if (!(0, types_1.isRecord)(store))
+            return null;
+        return store.routeNode ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/* -------------------------------------------------------------------------- */
+/* React Navigation                                                            */
+/* -------------------------------------------------------------------------- */
+const NAVIGATION_PARAM = /^:([A-Za-z0-9_]+)\??$/;
+/** A custom scheme beats an `https` prefix (the app opens from it directly); wildcard prefixes can't be used. */
+function pickPrefix(prefixes) {
+    if (!Array.isArray(prefixes))
+        return undefined;
+    const usable = prefixes.filter((prefix) => typeof prefix === 'string' && prefix !== '' && !prefix.includes('*'));
+    const custom = usable.find((prefix) => !/^https?:/i.test(prefix));
+    return custom ?? usable[0];
+}
+/** `<prefix>/<path>`; a prefix that is only a scheme ("wayfare://") takes the path right after it. */
+function linkFor(prefix, path) {
+    const scheme = /^([A-Za-z][A-Za-z0-9+.-]*):\/*$/.exec(prefix);
+    if (scheme)
+        return `${scheme[1]}://${path}`;
+    const base = prefix.replace(/\/+$/, '');
+    return path === '' ? base : `${base}/${path}`;
+}
+function joinPath(base, next, exact) {
+    const clean = next.replace(/^\/+|\/+$/g, '');
+    if (exact || base === '')
+        return clean;
+    return clean === '' ? base : `${base}/${clean}`;
+}
+/** The places in a React Navigation `linking.config`: each leaf screen, keyed by the screen names down to it. Exported for tests. */
+function placesFromLinking(linking) {
+    if (!(0, types_1.isRecord)(linking) || !(0, types_1.isRecord)(linking.config))
+        return [];
+    const prefix = pickPrefix(linking.prefixes);
+    const places = [];
+    const visit = (screens, names, base, depth) => {
+        if (!(0, types_1.isRecord)(screens) || depth > MAX_DEPTH)
+            return;
+        for (const [name, entry] of Object.entries(screens)) {
+            if (places.length >= MAX_PLACES)
+                return;
+            const here = [...names, name];
+            let path = base;
+            let nestedScreens;
+            if (typeof entry === 'string') {
+                path = joinPath(base, entry, false);
+            }
+            else if ((0, types_1.isRecord)(entry)) {
+                if (typeof entry.path === 'string')
+                    path = joinPath(base, entry.path, entry.exact === true);
+                nestedScreens = entry.screens;
+            }
+            if ((0, types_1.isRecord)(nestedScreens) && Object.keys(nestedScreens).length > 0) {
+                visit(nestedScreens, here, path, depth + 1);
+                continue;
+            }
+            const params = [];
+            for (const segment of path.split('/')) {
+                const match = NAVIGATION_PARAM.exec(segment);
+                if (match?.[1] !== undefined && !params.includes(match[1]))
+                    params.push(match[1]);
+            }
+            const place = { route: (0, placekey_1.routePattern)(here), params };
+            // A path that is only the base prefix is the app's root; a screen with no path at all has no link.
+            const hasPath = typeof entry === 'string' || ((0, types_1.isRecord)(entry) && typeof entry.path === 'string');
+            if (prefix !== undefined && hasPath) {
+                place.link = linkFor(prefix, path.replace(/:([A-Za-z0-9_]+)\??/g, '[$1]'));
+            }
+            places.push(place);
+        }
+    };
+    visit(linking.config.screens, [], '', 0);
+    return places;
+}
+/** The first thing `pick` returns for a fiber's props, walking the tree from the root, child first; null when none. */
+function findInFibers(pick) {
+    for (const root of (0, register_1.getRoots)()) {
+        const stack = root.current.child ? [root.current.child] : [];
+        let visited = 0;
+        for (let fiber = stack.pop(); fiber && visited < 5000; fiber = stack.pop()) {
+            visited += 1;
+            const found = pick((0, fiber_1.propsOf)(fiber));
+            if (found !== undefined)
+                return found;
+            if (fiber.sibling)
+                stack.push(fiber.sibling);
+            if (fiber.child)
+                stack.push(fiber.child);
+        }
+    }
+    return null;
+}
+/** The `linking` prop of the app's `NavigationContainer`, found through the fibers. */
+function findLinking() {
+    return findInFibers((props) => ((0, types_1.isRecord)(props.linking) && (0, types_1.isRecord)(props.linking.config) ? props.linking : undefined));
+}
+/* -------------------------------------------------------------------------- */
+/* The request                                                                 */
+/* -------------------------------------------------------------------------- */
+/** The `places` request: what the app's own route tree says it has, before any visit. Never throws. */
+function knownPlaces() {
+    try {
+        const scheme = (0, appinfo_1.appScheme)();
+        for (const read of [findRouterConfigNode, expoStoreRouteNode]) {
+            let node = null;
+            try {
+                node = read();
+            }
+            catch {
+                node = null; // an internal API that changed: try the next way
+            }
+            if (node === null)
+                continue;
+            const places = placesFromExpoTree(node, scheme);
+            if (places.length > 0)
+                return { source: 'expo-router', places };
+        }
+    }
+    catch {
+        // fall through
+    }
+    try {
+        const places = placesFromLinking(findLinking());
+        if (places.length > 0)
+            return { source: 'react-navigation', places };
+    }
+    catch {
+        // not a navigation app
+    }
+    return { source: 'none', places: [] };
+}
+//# sourceMappingURL=routetree.js.map

package/dist/routetree.js.map

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

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 /** Wire-protocol and shared types (see docs/PROTOCOL.md, version 1). */
 export declare const PROTOCOL_VERSION = 1;
-export type ErrorCode = 'not_found' | 'ambiguous' | 'not_actionable' | 'unsupported' | 'bad_params' | 'timeout' | 'internal';
+export type ErrorCode = 'not_found' | 'ambiguous' | 'not_actionable' | 'unsupported' | 'bad_params' | 'timeout' | 'stale' | 'internal';
 export interface WireError {
     code: ErrorCode;
     message: string;
@@ -8,13 +8,22 @@ export interface WireError {
     refs?: string[];
     /** The candidates as elements (role, id, actions, frame), only for `ambiguous`. */
     candidates?: TaplineElement[];
+    /** Facts about a refusal that carry no text from the app (whether a field is secure, never its value). */
+    data?: {
+        secure: boolean;
+    };
 }
 /** An error that maps 1:1 onto a protocol error response. */
 export declare class TaplineError extends Error {
     readonly code: ErrorCode;
     readonly refs: string[] | undefined;
     readonly candidates: TaplineElement[] | undefined;
-    constructor(code: ErrorCode, message: string, refs?: string[], candidates?: TaplineElement[]);
+    readonly data: {
+        secure: boolean;
+    } | undefined;
+    constructor(code: ErrorCode, message: string, refs?: string[], candidates?: TaplineElement[], data?: {
+        secure: boolean;
+    });
     toWire(): WireError;
 }
 export interface Frame {
@@ -45,6 +54,8 @@ export interface TaplineElement {
     selected: boolean;
     /** true / false / 'mixed' for checkable controls (Switch, checkbox role), else null. */
     checked: boolean | 'mixed' | null;
+    /** Inside a virtualized list's item: its text is content, so the host never saves it (AGENT-TOOLS 1.13 §18.2). */
+    row?: true;
 }
 export interface ScreenInfo {
     width: number;
@@ -119,12 +130,22 @@ export interface TreeResult {
         inFlight?: number;
         condition?: 'offline' | '3g' | 'lossy';
     };
+    /** Present (as "fast") while the `animations` command has fast-forwarded animations. */
+    animations?: 'fast';
     /** True while the software keyboard is up; absent when it is down or isn't known. */
     keyboard?: true;
     /** The focused screen, when the app uses React Navigation (Expo Router included). */
     route?: RouteInfo;
     /** With `changes: true` and a previous tree: what changed since then. */
     changes?: TreeChanges;
+    /** Where the app is: route pattern, tab and layer, never params (AGENT-TOOLS 1.13 §18.1). Always present: `route` is empty without a router. */
+    place?: PlaceState;
+}
+/** A place as a route key: route patterns only, never a param's value or any screen text. */
+export interface PlaceState {
+    route: string[];
+    tab?: string;
+    layer?: string;
 }
 export type Target = {
     ref: string;

package/dist/types.js

@@ -9,12 +9,14 @@ class TaplineError extends Error {
     code;
     refs;
     candidates;
-    constructor(code, message, refs, candidates) {
+    data;
+    constructor(code, message, refs, candidates, data) {
         super(message);
         this.name = 'TaplineError';
         this.code = code;
         this.refs = refs;
         this.candidates = candidates;
+        this.data = data;
     }
     toWire() {
         const wire = { code: this.code, message: this.message };
@@ -22,6 +24,8 @@ class TaplineError extends Error {
             wire.refs = this.refs;
         if (this.candidates)
             wire.candidates = this.candidates;
+        if (this.data)
+            wire.data = this.data;
         return wire;
     }
 }

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA,wEAAwE;;;AA6LxE,4BAEC;AA7LY,QAAA,gBAAgB,GAAG,CAAC,CAAC;AAoBlC,6DAA6D;AAC7D,MAAa,YAAa,SAAQ,KAAK;IAC5B,IAAI,CAAY;IAChB,IAAI,CAAuB;IAC3B,UAAU,CAA+B;IAElD,YAAY,IAAe,EAAE,OAAe,EAAE,IAAe,EAAE,UAA6B;QAC1F,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;IAED,MAAM;QACJ,MAAM,IAAI,GAAc,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;QACnE,IAAI,IAAI,CAAC,IAAI;YAAE,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACrC,IAAI,IAAI,CAAC,UAAU;YAAE,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QACvD,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAnBD,oCAmBC;AAmJD,SAAgB,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA,wEAAwE;;;AAgNxE,4BAEC;AAhNY,QAAA,gBAAgB,GAAG,CAAC,CAAC;AAuBlC,6DAA6D;AAC7D,MAAa,YAAa,SAAQ,KAAK;IAC5B,IAAI,CAAY;IAChB,IAAI,CAAuB;IAC3B,UAAU,CAA+B;IACzC,IAAI,CAAkC;IAE/C,YAAY,IAAe,EAAE,OAAe,EAAE,IAAe,EAAE,UAA6B,EAAE,IAA0B;QACtH,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,MAAM;QACJ,MAAM,IAAI,GAAc,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;QACnE,IAAI,IAAI,CAAC,IAAI;YAAE,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACrC,IAAI,IAAI,CAAC,UAAU;YAAE,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QACvD,IAAI,IAAI,CAAC,IAAI;YAAE,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACrC,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAtBD,oCAsBC;AAgKD,SAAgB,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC"}

package/dist/wait.d.ts

@@ -1,6 +1,11 @@
 type IdleProvider = () => boolean;
 /** Where "the network is quiet" comes from (the network tracker; tests). Null restores "always quiet". */
 export declare function setNetworkIdleProvider(provider: IdleProvider | null): void;
+export declare function waitFor(raw: {
+    once: true;
+} & Record<string, unknown>): Promise<{
+    found: boolean;
+}>;
 export declare function waitFor(raw: unknown): Promise<{
     met: true;
     waitedMs: number;