@symbiote-native/navigation 1.0.0

package/build-ngc/core/linking-config.d.ts

@@ -0,0 +1,13 @@
+import type { IRoute } from './navigator-state';
+export type IScreenLinkingConfig = string | {
+    path?: string;
+    screens?: Record<string, IScreenLinkingConfig>;
+};
+export type ILinkingConfig = {
+    prefixes: string[];
+    config: {
+        screens: Record<string, IScreenLinkingConfig>;
+    };
+};
+export declare function resolveRouteFromUrl(config: ILinkingConfig, url: string): IRoute<unknown> | null;
+export declare function resolveUrlFromRoute(config: ILinkingConfig, route: IRoute<unknown>): string | null;

package/build-ngc/core/linking-config.js

@@ -0,0 +1,172 @@
+// Linking config: the piece @react-navigation's `NavigationContainer`'s `linking` prop provides
+// on top of the framework-agnostic `Linking` module (core/engine/src/linking) — resolving a URL
+// ('myapp://user/42', '/user/42') to a route, and a route back to a URL. This is OUR OWN type,
+// not imported from react-navigation, kept close to its shape (`prefixes` + `config.screens`)
+// only so the DX is familiar.
+//
+// Why hand-rolled matching instead of react-router's `matchPath`/`generatePath` (evaluated per
+// task): react-router 8's package has no subpath export for the pure `lib/router/utils.ts`
+// matcher — its only general entry point (`.`) eagerly imports `./lib/dom/*`
+// (BrowserRouter/ScrollRestoration/cookies) and `./lib/server-runtime/*`, code that assumes DOM
+// and Node globals a Metro/Hermes RN bundle doesn't have; its `peerDependencies` also pin
+// `react-dom`, which this DOM-free monorepo never installs (see CLAUDE.md
+// react_native_is_an_explicit_top_level_peer — no foreign runtime singleton gets smuggled in).
+// On top of the bundling risk, `matchPath`'s/`generatePath`'s param-name extraction is a
+// template-literal-type trick that only fires for a compile-time LITERAL path string; our
+// patterns come from a runtime config object (`Path` widens to plain `string`), so the generic
+// degrades to an empty params type and using the result would force an `as` cast — forbidden by
+// this project's TS conventions. A minimal `:param`-segment matcher sidesteps both problems and
+// is the right size for a single flat Stack (no optional/splat segments — no nested-navigator use
+// for them yet).
+import { dlog } from '@symbiote-native/engine';
+import { isRecord } from './guards';
+// Strips leading/trailing slashes so segments join predictably regardless of how the caller
+// wrote a path ('feed/:sort', '/feed/:sort/', etc).
+function normalizeSegment(segment) {
+    return segment.replace(/^\/+|\/+$/g, '');
+}
+function joinPath(parent, child) {
+    const parts = [normalizeSegment(parent), normalizeSegment(child)].filter(part => part.length > 0);
+    return parts.join('/');
+}
+// Walks `screens` recursively, accumulating the path down to each LEAF screen. Unlike
+// react-navigation (which resolves nested config into nested navigation state), our navigator is
+// a single flat Stack — a `screens` group with no `path` of its own is transparent (consumes no
+// URL segment); a group WITH a `path` but no nested `screens` is itself a leaf using that path.
+function flattenScreens(screens, parentPath, out) {
+    for (const [name, entry] of Object.entries(screens)) {
+        if (typeof entry === 'string') {
+            out.push({ name, pattern: joinPath(parentPath, entry) });
+            continue;
+        }
+        const nextParent = entry.path !== undefined ? joinPath(parentPath, entry.path) : parentPath;
+        if (entry.screens !== undefined) {
+            flattenScreens(entry.screens, nextParent, out);
+        }
+        else if (entry.path !== undefined) {
+            out.push({ name, pattern: nextParent });
+        }
+        else {
+            dlog(`linking-config: screen "${name}" has neither a path nor nested screens, skipping`);
+        }
+    }
+    return out;
+}
+function dynamicSegmentCount(pattern) {
+    if (pattern.length === 0)
+        return 0;
+    return pattern.split('/').filter(segment => segment.startsWith(':')).length;
+}
+function segmentCount(pattern) {
+    return pattern.length === 0 ? 0 : pattern.split('/').length;
+}
+// More static segments should win over a param that would also match (e.g. a literal
+// '/user/me' pattern over '/user/:id'), mirroring how react-navigation prefers exact matches.
+function bySpecificity(a, b) {
+    const dynamicDiff = dynamicSegmentCount(a.pattern) - dynamicSegmentCount(b.pattern);
+    if (dynamicDiff !== 0)
+        return dynamicDiff;
+    return segmentCount(b.pattern) - segmentCount(a.pattern);
+}
+function matchPattern(pattern, pathname) {
+    const patternSegments = pattern.length === 0 ? [] : pattern.split('/');
+    const pathSegments = pathname.length === 0 ? [] : pathname.split('/');
+    if (patternSegments.length !== pathSegments.length)
+        return null;
+    const params = {};
+    for (let index = 0; index < patternSegments.length; index += 1) {
+        const patternSegment = patternSegments[index];
+        const pathSegment = pathSegments[index];
+        if (patternSegment.startsWith(':')) {
+            params[patternSegment.slice(1)] = decodeURIComponent(pathSegment);
+        }
+        else if (patternSegment !== pathSegment) {
+            return null;
+        }
+    }
+    return params;
+}
+function stripQueryAndHash(url) {
+    const match = /[?#]/.exec(url);
+    return match === null ? url : url.slice(0, match.index);
+}
+// Resolves a full URL down to the bare path segment string ('user/42', no leading slash) by
+// stripping the longest matching configured prefix, falling back to treating the URL as an
+// already-bare path when it starts with '/' (the task's second example form). Returns null when
+// neither applies — an unrecognized scheme/host, not "no route matched".
+function extractPathname(config, url) {
+    const withoutQuery = stripQueryAndHash(url);
+    const sortedPrefixes = [...config.prefixes].sort((a, b) => b.length - a.length);
+    for (const prefix of sortedPrefixes) {
+        if (withoutQuery.startsWith(prefix)) {
+            return normalizeSegment(withoutQuery.slice(prefix.length));
+        }
+    }
+    if (withoutQuery.startsWith('/'))
+        return normalizeSegment(withoutQuery);
+    return null;
+}
+export function resolveRouteFromUrl(config, url) {
+    const pathname = extractPathname(config, url);
+    if (pathname === null) {
+        dlog(`linking-config: url "${url}" matched no configured prefix`);
+        return null;
+    }
+    const candidates = flattenScreens(config.config.screens, '', []).sort(bySpecificity);
+    for (const candidate of candidates) {
+        const params = matchPattern(candidate.pattern, pathname);
+        if (params !== null) {
+            dlog(`linking-config: resolved "${url}" -> ${candidate.name}`);
+            // `key` is not real route identity here — the navigator mints its own on push/replace
+            // (stack.ts's createRoute); `name` is a stable enough placeholder to satisfy IRoute's shape.
+            return {
+                key: candidate.name,
+                name: candidate.name,
+                params: Object.keys(params).length > 0 ? params : undefined,
+            };
+        }
+    }
+    dlog(`linking-config: url "${url}" (path "${pathname}") matched no configured screen`);
+    return null;
+}
+// The inverse of matchPattern: fills a pattern's ':param' segments from `params`, or returns
+// null when a required param is missing (mirrors react-router's generatePath throwing, minus the
+// throw — a resolver returning null reads more naturally at the call site here).
+function fillPattern(pattern, params) {
+    if (pattern.length === 0)
+        return '';
+    const source = isRecord(params) ? params : {};
+    const segments = [];
+    for (const segment of pattern.split('/')) {
+        if (!segment.startsWith(':')) {
+            segments.push(segment);
+            continue;
+        }
+        const value = source[segment.slice(1)];
+        if (value === undefined || value === null)
+            return null;
+        segments.push(encodeURIComponent(String(value)));
+    }
+    return segments.join('/');
+}
+export function resolveUrlFromRoute(config, route) {
+    const candidate = flattenScreens(config.config.screens, '', []).find(entry => entry.name === route.name);
+    if (candidate === undefined) {
+        dlog(`linking-config: no configured screen for route name "${route.name}"`);
+        return null;
+    }
+    const path = fillPattern(candidate.pattern, route.params);
+    if (path === null) {
+        dlog(`linking-config: route "${route.name}" is missing a param required by "${candidate.pattern}"`);
+        return null;
+    }
+    const prefix = config.prefixes[0];
+    if (prefix === undefined)
+        return path.length > 0 ? `/${path}` : '/';
+    // A prefix already carrying its own trailing separator ('myapp://') must not be truncated to
+    // 'myapp:/' by naively slicing one char off — only add a '/' when the prefix doesn't have one.
+    if (path.length === 0)
+        return prefix;
+    return prefix.endsWith('/') ? `${prefix}${path}` : `${prefix}/${path}`;
+}
+//# sourceMappingURL=linking-config.js.map

package/build-ngc/core/linking-config.js.map

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

package/build-ngc/core/navigation-events/index.d.ts

@@ -0,0 +1,16 @@
+export declare const NAVIGATION_EVENT_FOCUS = "focus";
+export declare const NAVIGATION_EVENT_BLUR = "blur";
+export declare const NAVIGATION_EVENT_STATE = "state";
+export declare const NAVIGATION_EVENT_BEFORE_REMOVE = "beforeRemove";
+export type INavigationEventName = typeof NAVIGATION_EVENT_FOCUS | typeof NAVIGATION_EVENT_BLUR | typeof NAVIGATION_EVENT_STATE | typeof NAVIGATION_EVENT_BEFORE_REMOVE;
+export type INavigationEventListener<TData = unknown> = (data: TData) => void;
+export type INavigationEmitter = {
+    emit: (event: INavigationEventName, data?: unknown) => void;
+    addListener: (event: INavigationEventName, listener: INavigationEventListener) => () => void;
+};
+export declare function createNavigationEmitter(): INavigationEmitter;
+export type IFocusTransition = {
+    blurKey?: string;
+    focusKey?: string;
+};
+export declare function diffFocusedRoute(prevKey: string | undefined, nextKey: string | undefined): IFocusTransition;

package/build-ngc/core/navigation-events/index.js

@@ -0,0 +1,58 @@
+// The framework-agnostic half of what @react-navigation exposes as `navigation.addListener` /
+// `useFocusEffect` / `useIsFocused` / `useNavigationState`: a plain pub/sub emitter, zero React.
+// addListener is NOT React-specific there either - React's hooks are thin useEffect wrappers
+// around exactly this subscribe/unsubscribe shape (confirmed against the 8.x docs: `const
+// unsubscribe = navigation.addListener('focus', cb); return unsubscribe;` inside a bare
+// `useEffect`). One emitter per route (created by the adapter, e.g. stack.ts's per-route
+// `emitters` map) carries that route's own focus/blur/state lifecycle; every adapter's lifecycle
+// hooks subscribe to it, matching this file's single responsibility split from `constants.ts`
+// (which only names Fabric view/prop-key strings, not this JS-only event system).
+//
+// diffFocusedRoute below centralizes the "which route lost focus, which gained it" comparison
+// that tabs.ts and drawer.ts independently reimplemented in all three adapters (each watching its
+// own router state for the focused index/key changing, then manually emitting BLUR to the old key
+// and FOCUS to the new one, plus an initial FOCUS seed on first mount) - the diff is pure and
+// identical everywhere; only WHEN to run it differs per framework (a `useEffect` dependency array,
+// a Vue `watch`, an idempotent-per-read Angular method), so that half stays adapter-owned.
+import { dlog } from '@symbiote-native/engine';
+export const NAVIGATION_EVENT_FOCUS = 'focus';
+export const NAVIGATION_EVENT_BLUR = 'blur';
+export const NAVIGATION_EVENT_STATE = 'state';
+export const NAVIGATION_EVENT_BEFORE_REMOVE = 'beforeRemove';
+export function createNavigationEmitter() {
+    const listenersByEvent = new Map();
+    function addListener(event, listener) {
+        let listeners = listenersByEvent.get(event);
+        if (!listeners) {
+            listeners = new Set();
+            listenersByEvent.set(event, listeners);
+        }
+        listeners.add(listener);
+        return () => {
+            listeners?.delete(listener);
+        };
+    }
+    function emit(event, data) {
+        const listeners = listenersByEvent.get(event);
+        // Investigation instrumentation (flicker-on-focus bug): every emission, whether or not a
+        // listener is attached, so the log stream shows if focus/blur ever fires with 0 subscribers
+        // (a silent no-op) vs racing an actual effect. Kept behind DEBUG, never removed.
+        dlog(`Navigation emitter: emit "${event}" (${listeners?.size ?? 0} listener(s)) at t=${Date.now()}`);
+        if (!listeners)
+            return;
+        for (const listener of listeners)
+            listener(data);
+    }
+    return { emit, addListener };
+}
+export function diffFocusedRoute(prevKey, nextKey) {
+    if (prevKey === nextKey)
+        return {};
+    const transition = {};
+    if (prevKey !== undefined)
+        transition.blurKey = prevKey;
+    if (nextKey !== undefined)
+        transition.focusKey = nextKey;
+    return transition;
+}
+//# sourceMappingURL=index.js.map

package/build-ngc/core/navigation-events/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/navigation-events/index.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,iGAAiG;AACjG,6FAA6F;AAC7F,0FAA0F;AAC1F,wFAAwF;AACxF,yFAAyF;AACzF,iGAAiG;AACjG,8FAA8F;AAC9F,kFAAkF;AAClF,EAAE;AACF,8FAA8F;AAC9F,kGAAkG;AAClG,kGAAkG;AAClG,8FAA8F;AAC9F,mGAAmG;AACnG,2FAA2F;AAE3F,OAAO,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAE/C,MAAM,CAAC,MAAM,sBAAsB,GAAG,OAAO,CAAC;AAC9C,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC;AAC5C,MAAM,CAAC,MAAM,sBAAsB,GAAG,OAAO,CAAC;AAC9C,MAAM,CAAC,MAAM,8BAA8B,GAAG,cAAc,CAAC;AAe7D,MAAM,UAAU,uBAAuB;IACrC,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAAuD,CAAC;IAExF,SAAS,WAAW,CAClB,KAA2B,EAC3B,QAAkC;QAElC,IAAI,SAAS,GAAG,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC5C,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,SAAS,GAAG,IAAI,GAAG,EAAE,CAAC;YACtB,gBAAgB,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;QACzC,CAAC;QACD,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAExB,OAAO,GAAG,EAAE;YACV,SAAS,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC9B,CAAC,CAAC;IACJ,CAAC;IAED,SAAS,IAAI,CAAC,KAA2B,EAAE,IAAc;QACvD,MAAM,SAAS,GAAG,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC9C,yFAAyF;QACzF,4FAA4F;QAC5F,iFAAiF;QACjF,IAAI,CACF,6BAA6B,KAAK,MAAM,SAAS,EAAE,IAAI,IAAI,CAAC,sBAAsB,IAAI,CAAC,GAAG,EAAE,EAAE,CAC/F,CAAC;QACF,IAAI,CAAC,SAAS;YAAE,OAAO;QACvB,KAAK,MAAM,QAAQ,IAAI,SAAS;YAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IACnD,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;AAC/B,CAAC;AAeD,MAAM,UAAU,gBAAgB,CAC9B,OAA2B,EAC3B,OAA2B;IAE3B,IAAI,OAAO,KAAK,OAAO;QAAE,OAAO,EAAE,CAAC;IACnC,MAAM,UAAU,GAAqB,EAAE,CAAC;IACxC,IAAI,OAAO,KAAK,SAAS;QAAE,UAAU,CAAC,OAAO,GAAG,OAAO,CAAC;IACxD,IAAI,OAAO,KAAK,SAAS;QAAE,UAAU,CAAC,QAAQ,GAAG,OAAO,CAAC;IACzD,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/build-ngc/core/navigation-events.d.ts

@@ -0,0 +1,16 @@
+export declare const NAVIGATION_EVENT_FOCUS = "focus";
+export declare const NAVIGATION_EVENT_BLUR = "blur";
+export declare const NAVIGATION_EVENT_STATE = "state";
+export declare const NAVIGATION_EVENT_BEFORE_REMOVE = "beforeRemove";
+export type INavigationEventName = typeof NAVIGATION_EVENT_FOCUS | typeof NAVIGATION_EVENT_BLUR | typeof NAVIGATION_EVENT_STATE | typeof NAVIGATION_EVENT_BEFORE_REMOVE;
+export type INavigationEventListener<TData = unknown> = (data: TData) => void;
+export type INavigationEmitter = {
+    emit: (event: INavigationEventName, data?: unknown) => void;
+    addListener: (event: INavigationEventName, listener: INavigationEventListener) => () => void;
+};
+export declare function createNavigationEmitter(): INavigationEmitter;
+export type IFocusTransition = {
+    blurKey?: string;
+    focusKey?: string;
+};
+export declare function diffFocusedRoute(prevKey: string | undefined, nextKey: string | undefined): IFocusTransition;

package/build-ngc/core/navigation-events.js

@@ -0,0 +1,58 @@
+// The framework-agnostic half of what @react-navigation exposes as `navigation.addListener` /
+// `useFocusEffect` / `useIsFocused` / `useNavigationState`: a plain pub/sub emitter, zero React.
+// addListener is NOT React-specific there either — React's hooks are thin useEffect wrappers
+// around exactly this subscribe/unsubscribe shape (confirmed against the 8.x docs: `const
+// unsubscribe = navigation.addListener('focus', cb); return unsubscribe;` inside a bare
+// `useEffect`). One emitter per route (created by the adapter, e.g. stack.ts's per-route
+// `emitters` map) carries that route's own focus/blur/state lifecycle; every adapter's lifecycle
+// hooks subscribe to it, matching this file's single responsibility split from `constants.ts`
+// (which only names Fabric view/prop-key strings, not this JS-only event system).
+//
+// diffFocusedRoute below centralizes the "which route lost focus, which gained it" comparison
+// that tabs.ts and drawer.ts independently reimplemented in all three adapters (each watching its
+// own router state for the focused index/key changing, then manually emitting BLUR to the old key
+// and FOCUS to the new one, plus an initial FOCUS seed on first mount) — the diff is pure and
+// identical everywhere; only WHEN to run it differs per framework (a `useEffect` dependency array,
+// a Vue `watch`, an idempotent-per-read Angular method), so that half stays adapter-owned.
+import { dlog } from '@symbiote-native/engine';
+export const NAVIGATION_EVENT_FOCUS = 'focus';
+export const NAVIGATION_EVENT_BLUR = 'blur';
+export const NAVIGATION_EVENT_STATE = 'state';
+export const NAVIGATION_EVENT_BEFORE_REMOVE = 'beforeRemove';
+export function createNavigationEmitter() {
+    const listenersByEvent = new Map();
+    function addListener(event, listener) {
+        let listeners = listenersByEvent.get(event);
+        if (!listeners) {
+            listeners = new Set();
+            listenersByEvent.set(event, listeners);
+        }
+        listeners.add(listener);
+        return () => {
+            listeners?.delete(listener);
+        };
+    }
+    function emit(event, data) {
+        const listeners = listenersByEvent.get(event);
+        // Investigation instrumentation (flicker-on-focus bug): every emission, whether or not a
+        // listener is attached, so the log stream shows if focus/blur ever fires with 0 subscribers
+        // (a silent no-op) vs racing an actual effect. Kept behind DEBUG, never removed.
+        dlog(`Navigation emitter: emit "${event}" (${listeners?.size ?? 0} listener(s)) at t=${Date.now()}`);
+        if (!listeners)
+            return;
+        for (const listener of listeners)
+            listener(data);
+    }
+    return { emit, addListener };
+}
+export function diffFocusedRoute(prevKey, nextKey) {
+    if (prevKey === nextKey)
+        return {};
+    const transition = {};
+    if (prevKey !== undefined)
+        transition.blurKey = prevKey;
+    if (nextKey !== undefined)
+        transition.focusKey = nextKey;
+    return transition;
+}
+//# sourceMappingURL=navigation-events.js.map

package/build-ngc/core/navigation-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation-events.js","sourceRoot":"","sources":["../../src/core/navigation-events.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,iGAAiG;AACjG,6FAA6F;AAC7F,0FAA0F;AAC1F,wFAAwF;AACxF,yFAAyF;AACzF,iGAAiG;AACjG,8FAA8F;AAC9F,kFAAkF;AAClF,EAAE;AACF,8FAA8F;AAC9F,kGAAkG;AAClG,kGAAkG;AAClG,8FAA8F;AAC9F,mGAAmG;AACnG,2FAA2F;AAE3F,OAAO,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAE/C,MAAM,CAAC,MAAM,sBAAsB,GAAG,OAAO,CAAC;AAC9C,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC;AAC5C,MAAM,CAAC,MAAM,sBAAsB,GAAG,OAAO,CAAC;AAC9C,MAAM,CAAC,MAAM,8BAA8B,GAAG,cAAc,CAAC;AAe7D,MAAM,UAAU,uBAAuB;IACrC,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAAuD,CAAC;IAExF,SAAS,WAAW,CAClB,KAA2B,EAC3B,QAAkC;QAElC,IAAI,SAAS,GAAG,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC5C,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,SAAS,GAAG,IAAI,GAAG,EAAE,CAAC;YACtB,gBAAgB,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;QACzC,CAAC;QACD,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAExB,OAAO,GAAG,EAAE;YACV,SAAS,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC9B,CAAC,CAAC;IACJ,CAAC;IAED,SAAS,IAAI,CAAC,KAA2B,EAAE,IAAc;QACvD,MAAM,SAAS,GAAG,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC9C,yFAAyF;QACzF,4FAA4F;QAC5F,iFAAiF;QACjF,IAAI,CACF,6BAA6B,KAAK,MAAM,SAAS,EAAE,IAAI,IAAI,CAAC,sBAAsB,IAAI,CAAC,GAAG,EAAE,EAAE,CAC/F,CAAC;QACF,IAAI,CAAC,SAAS;YAAE,OAAO;QACvB,KAAK,MAAM,QAAQ,IAAI,SAAS;YAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IACnD,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;AAC/B,CAAC;AAeD,MAAM,UAAU,gBAAgB,CAC9B,OAA2B,EAC3B,OAA2B;IAE3B,IAAI,OAAO,KAAK,OAAO;QAAE,OAAO,EAAE,CAAC;IACnC,MAAM,UAAU,GAAqB,EAAE,CAAC;IACxC,IAAI,OAAO,KAAK,SAAS;QAAE,UAAU,CAAC,OAAO,GAAG,OAAO,CAAC;IACxD,IAAI,OAAO,KAAK,SAAS;QAAE,UAAU,CAAC,QAAQ,GAAG,OAAO,CAAC;IACzD,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/build-ngc/core/navigator-handles/index.d.ts

@@ -0,0 +1,30 @@
+import type { INavigatorState } from '../navigator-state';
+import type { IDrawerScreenOptions } from '../drawer-options';
+export type INavigatorHandle = {
+    push: (name: string, params?: unknown) => void;
+    pop: (count?: number) => void;
+    popToTop: () => void;
+    popTo: (key: string) => void;
+    replace: (name: string, params?: unknown) => void;
+    setParams: (params: unknown, key?: string) => void;
+    reset: (state: INavigatorState) => void;
+    canGoBack: () => boolean;
+};
+export type ITabNavigatorHandle = {
+    jumpTo: (name: string, params?: unknown) => void;
+    setParams: (params: unknown, key: string) => void;
+};
+export type IDrawerNavigatorHandle = {
+    openDrawer: () => void;
+    closeDrawer: () => void;
+    toggleDrawer: () => void;
+    jumpTo: (name: string) => void;
+};
+export type IDrawerDescriptorMap = Record<string, {
+    options: IDrawerScreenOptions;
+    navigation: IDrawerNavigatorHandle;
+}>;
+export type IAnyNavigatorHandle = INavigatorHandle | ITabNavigatorHandle | IDrawerNavigatorHandle;
+export declare function isStackNavigatorHandle(handle: IAnyNavigatorHandle): handle is INavigatorHandle;
+export declare function isDrawerNavigatorHandle(handle: IAnyNavigatorHandle): handle is IDrawerNavigatorHandle;
+export declare function isTabNavigatorHandle(handle: IAnyNavigatorHandle): handle is ITabNavigatorHandle;

package/build-ngc/core/navigator-handles/index.js

@@ -0,0 +1,16 @@
+// Imperative navigator handles: framework-agnostic (scalars, `unknown`, plain function
+// signatures over `INavigatorState`/`IDrawerScreenOptions` - no framework element, ref, or
+// children in any field), so each shape is declared once here and every adapter re-exports it
+// verbatim (see CLAUDE.md <prop_types_split_agnostic_vs_per_adapter>).
+export function isStackNavigatorHandle(handle) {
+    return 'push' in handle;
+}
+export function isDrawerNavigatorHandle(handle) {
+    return 'openDrawer' in handle;
+}
+// jumpTo exists on both Tab and Drawer handles, so a Tab handle is a jumpTo-having handle that
+// isn't a Drawer handle (Drawer's own openDrawer/closeDrawer/toggleDrawer rule it out).
+export function isTabNavigatorHandle(handle) {
+    return 'jumpTo' in handle && !isDrawerNavigatorHandle(handle);
+}
+//# sourceMappingURL=index.js.map

package/build-ngc/core/navigator-handles/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/navigator-handles/index.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,2FAA2F;AAC3F,8FAA8F;AAC9F,uEAAuE;AA6CvE,MAAM,UAAU,sBAAsB,CAAC,MAA2B;IAChE,OAAO,MAAM,IAAI,MAAM,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,MAA2B;IAE3B,OAAO,YAAY,IAAI,MAAM,CAAC;AAChC,CAAC;AAED,+FAA+F;AAC/F,wFAAwF;AACxF,MAAM,UAAU,oBAAoB,CAAC,MAA2B;IAC9D,OAAO,QAAQ,IAAI,MAAM,IAAI,CAAC,uBAAuB,CAAC,MAAM,CAAC,CAAC;AAChE,CAAC"}

package/build-ngc/core/navigator-handles.d.ts

@@ -0,0 +1,30 @@
+import type { INavigatorState } from './navigator-state';
+import type { IDrawerScreenOptions } from './drawer-options';
+export type INavigatorHandle = {
+    push: (name: string, params?: unknown) => void;
+    pop: (count?: number) => void;
+    popToTop: () => void;
+    popTo: (key: string) => void;
+    replace: (name: string, params?: unknown) => void;
+    setParams: (params: unknown, key?: string) => void;
+    reset: (state: INavigatorState) => void;
+    canGoBack: () => boolean;
+};
+export type ITabNavigatorHandle = {
+    jumpTo: (name: string, params?: unknown) => void;
+    setParams: (params: unknown, key: string) => void;
+};
+export type IDrawerNavigatorHandle = {
+    openDrawer: () => void;
+    closeDrawer: () => void;
+    toggleDrawer: () => void;
+    jumpTo: (name: string) => void;
+};
+export type IDrawerDescriptorMap = Record<string, {
+    options: IDrawerScreenOptions;
+    navigation: IDrawerNavigatorHandle;
+}>;
+export type IAnyNavigatorHandle = INavigatorHandle | ITabNavigatorHandle | IDrawerNavigatorHandle;
+export declare function isStackNavigatorHandle(handle: IAnyNavigatorHandle): handle is INavigatorHandle;
+export declare function isDrawerNavigatorHandle(handle: IAnyNavigatorHandle): handle is IDrawerNavigatorHandle;
+export declare function isTabNavigatorHandle(handle: IAnyNavigatorHandle): handle is ITabNavigatorHandle;

package/build-ngc/core/navigator-handles.js

@@ -0,0 +1,16 @@
+// Imperative navigator handles: framework-agnostic (scalars, `unknown`, plain function
+// signatures over `INavigatorState`/`IDrawerScreenOptions` — no framework element, ref, or
+// children in any field), so each shape is declared once here and every adapter re-exports it
+// verbatim (see CLAUDE.md <prop_types_split_agnostic_vs_per_adapter>).
+export function isStackNavigatorHandle(handle) {
+    return 'push' in handle;
+}
+export function isDrawerNavigatorHandle(handle) {
+    return 'openDrawer' in handle;
+}
+// jumpTo exists on both Tab and Drawer handles, so a Tab handle is a jumpTo-having handle that
+// isn't a Drawer handle (Drawer's own openDrawer/closeDrawer/toggleDrawer rule it out).
+export function isTabNavigatorHandle(handle) {
+    return 'jumpTo' in handle && !isDrawerNavigatorHandle(handle);
+}
+//# sourceMappingURL=navigator-handles.js.map

package/build-ngc/core/navigator-handles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigator-handles.js","sourceRoot":"","sources":["../../src/core/navigator-handles.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,2FAA2F;AAC3F,8FAA8F;AAC9F,uEAAuE;AA6CvE,MAAM,UAAU,sBAAsB,CAAC,MAA2B;IAChE,OAAO,MAAM,IAAI,MAAM,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,MAA2B;IAE3B,OAAO,YAAY,IAAI,MAAM,CAAC;AAChC,CAAC;AAED,+FAA+F;AAC/F,wFAAwF;AACxF,MAAM,UAAU,oBAAoB,CAAC,MAA2B;IAC9D,OAAO,QAAQ,IAAI,MAAM,IAAI,CAAC,uBAAuB,CAAC,MAAM,CAAC,CAAC;AAChE,CAAC"}