@resistdesign/voltra 3.0.0-alpha.20 → 3.0.0-alpha.22

package/README.md

@@ -125,13 +125,15 @@ EasyLayout now has:
 - Web rendering via CSS Grid in `@resistdesign/voltra/web`.
 - Native coordinate computation in `@resistdesign/voltra/native`.
 
-### Examples
+### Reference Examples
 
-- `examples/api.ts`
-- `examples/common.ts`
-- `examples/web.ts`
-- `examples/native.ts`
-- `examples/build.ts`
+- Index: `examples/README.md`
+- Client routing: `examples/routing/app-routing.ts`
+- Backend API routing: `examples/api/backend-routing.ts`
+- Forms: `examples/forms/`
+- Layout: `examples/layout/`
+- Common types: `examples/common/types.ts`
+- Build-time parsing: `examples/build/type-parsing.ts`
 
 ### Template syntax
 
@@ -189,50 +191,43 @@ const coords = layout.computeNativeCoords({
 
 ## Routing (Web + Native)
 
-Voltra ships a render-agnostic Route core in `@resistdesign/voltra/app` plus platform adapters.
+Voltra routing is unified under `@resistdesign/voltra/app`.
 
-Web usage (auto-wires `window.history`):
+Reference example: `examples/routing/app-routing.ts`
 
 ```tsx
-import { Route } from "@resistdesign/voltra/web";
+import { Route } from "@resistdesign/voltra/app";
+
+<Route>
+  <Route path="/" exact>
+    <HomeScreen />
+  </Route>
+  <Route path="/login" exact>
+    <LoginScreen />
+  </Route>
+  <Route path="/signup" exact>
+    <SignUpScreen />
+  </Route>
+</Route>;
 ```
 
-Native usage (adapter-driven):
+How it works:
 
-```tsx
-import { Route, RouteProvider, createManualRouteAdapter } from "@resistdesign/voltra/native";
-const { adapter, updatePath } = createManualRouteAdapter("/home");
-```
+- Root `<Route>` (no `path`) is provider mode.
+- Nested `<Route path="...">` entries are matcher mode.
+- Strategy is auto-selected:
+  - DOM + History API => browser history strategy.
+  - Otherwise => in-memory native strategy.
 
-For React Native navigation libraries, Voltra is optimized for react-navigation as the primary native default. Provide a RouteAdapter that maps navigation state to a path and call `RouteProvider`.
+Escape hatches (root-only):
 
-Native navigation mapping example:
+- `initialPath` sets fallback startup path when no ingress URL exists.
+- `adapter` allows full custom adapter control.
+- `ingress` supports deep-link ingress wiring (`getInitialURL`, `subscribe`, URL mapping, push/replace mode).
 
-```tsx
-import { buildPathFromRouteChain, createNavigationStateRouteAdapter } from "@resistdesign/voltra/native";
-
-const adapter = createNavigationStateRouteAdapter({
-  getState: () => navigationRef.getRootState(),
-  subscribe: (listener) => navigationRef.addListener("state", listener),
-  toPath: (state) =>
-    buildPathFromRouteChain(
-      state.routes.map((route) => ({
-        name: route.name,
-        params: route.params as Record<string, any>,
-      })),
-      {
-        Home: "home",
-        Book: "books/:id",
-      },
-    ),
-  navigate: (path) => {
-    const routeName = path === "/home" ? "Home" : "Book";
-    navigationRef.navigate(routeName);
-  },
-});
-```
+If you are looking for backend request routing (Cloud Function/API event routing), see:
 
-For RN web builds, keep your navigation library linking config in sync with the same route patterns used in `buildPathFromRouteChain`.
+- `examples/api/backend-routing.ts`
 
 ## Form Suites (Web + Native + BYOCS)
 

package/api/index.d.ts

@@ -45,6 +45,10 @@
  * ```
  *
  * See also: `@resistdesign/voltra/app` for client-side app helpers.
+ *
+ * Reference examples:
+ * - `examples/README.md`
+ * - `examples/api/backend-routing.ts`
  */
 /**
  * @category api

package/app/index.d.ts

@@ -17,6 +17,10 @@
  * @see {@link useApplicationStateValueStructure} and
  * {@link useApplicationStateLoader} for good starting points.
  *
+ * Reference examples:
+ * - `examples/README.md`
+ * - `examples/routing/app-routing.ts`
+ *
  * @example
  * ```tsx
  * import {

package/app/index.js

@@ -157,6 +157,23 @@ var mergeStringPaths = (path1, path2, delimiter = PATH_DELIMITER, filterEmptyOut
   useJson,
   uriEncodeParts
 );
+var resolvePath = (currentPath, newPath) => {
+  const newSegments = getPathArray(newPath, PATH_DELIMITER, true);
+  let currentSegments = getPathArray(currentPath, PATH_DELIMITER, true);
+  if (newPath.startsWith("/")) {
+    currentSegments = [];
+  }
+  newSegments.forEach((segment) => {
+    if (segment === "..") {
+      if (currentSegments.length > 0) {
+        currentSegments.pop();
+      }
+    } else if (segment !== ".") {
+      currentSegments.push(segment);
+    }
+  });
+  return "/" + currentSegments.join("/");
+};
 var getParamsAndTestPath = (path, testPath, exact = false) => {
   const pathList = getPathArray(path);
   const testPathList = getPathArray(testPath);
@@ -724,6 +741,177 @@ var createMemoryHistory = (initialPath = "/") => {
     }
   };
 };
+
+// src/app/utils/RouteHistory.ts
+var createRouteAdapterFromHistory = (history) => {
+  return {
+    getPath: () => history.location.path,
+    subscribe: (listener) => {
+      return history.listen((location) => {
+        listener(location.path);
+      });
+    },
+    push: (path) => {
+      history.push(path, { replaceSearch: true });
+    },
+    replace: (path) => {
+      history.replace(path, { replaceSearch: true });
+    }
+  };
+};
+
+// src/app/utils/UniversalRouteAdapter.ts
+var getWindow = () => {
+  if (typeof globalThis === "undefined") {
+    return void 0;
+  }
+  if ("window" in globalThis) {
+    return globalThis.window;
+  }
+  return void 0;
+};
+var canUseBrowserHistory = () => {
+  const WINDOW = getWindow();
+  return Boolean(
+    WINDOW && WINDOW.location && WINDOW.history && typeof WINDOW.history.pushState === "function"
+  );
+};
+var createBrowserRouteAdapter = () => {
+  const WINDOW = getWindow();
+  const listeners = /* @__PURE__ */ new Set();
+  const notify = () => {
+    const path = WINDOW?.location?.pathname ?? "";
+    listeners.forEach((listener) => listener(path));
+  };
+  const handleHistoryEvent = () => {
+    notify();
+  };
+  return {
+    getPath: () => WINDOW?.location?.pathname ?? "",
+    subscribe: (listener) => {
+      listeners.add(listener);
+      if (WINDOW) {
+        WINDOW.addEventListener("popstate", handleHistoryEvent);
+        WINDOW.addEventListener("statechanged", handleHistoryEvent);
+      }
+      return () => {
+        listeners.delete(listener);
+        if (WINDOW) {
+          WINDOW.removeEventListener("popstate", handleHistoryEvent);
+          WINDOW.removeEventListener("statechanged", handleHistoryEvent);
+        }
+      };
+    },
+    push: (path, title = "") => {
+      if (!WINDOW?.history) {
+        return;
+      }
+      const targetPath = parseHistoryPath(path).path;
+      if (targetPath === (WINDOW.location?.pathname ?? "")) {
+        return;
+      }
+      WINDOW.history.pushState({}, title, path);
+      notify();
+    },
+    replace: (path, title = "") => {
+      if (!WINDOW?.history?.replaceState) {
+        return;
+      }
+      const targetPath = parseHistoryPath(path).path;
+      if (targetPath === (WINDOW.location?.pathname ?? "")) {
+        return;
+      }
+      WINDOW.history.replaceState({}, title, path);
+      notify();
+    }
+  };
+};
+var createNativeRouteAdapter = (initialPath = "/", ingress) => {
+  const mapURLToPath = ingress?.mapURLToPath ?? ((url) => buildHistoryPath(parseHistoryPath(url)));
+  const onIncomingURL = ingress?.onIncomingURL ?? "replace";
+  const history = createMemoryHistory(initialPath);
+  const adapter = createRouteAdapterFromHistory(history);
+  let stopIngress;
+  let started = false;
+  let subscribers = 0;
+  const applyPath = (path, mode) => {
+    const normalizedPath = parseHistoryPath(path).path;
+    if (!normalizedPath || normalizedPath === history.location.path) {
+      return;
+    }
+    if (mode === "push") {
+      history.push(normalizedPath, { replaceSearch: true });
+      return;
+    }
+    history.replace(normalizedPath, { replaceSearch: true });
+  };
+  const startIngress = async () => {
+    if (started || !ingress) {
+      return;
+    }
+    started = true;
+    const startKey = history.location.key;
+    const startIndex = history.index;
+    if (ingress.subscribe) {
+      stopIngress = ingress.subscribe((url) => {
+        const nextPath = mapURLToPath(url);
+        if (!nextPath) {
+          return;
+        }
+        applyPath(nextPath, onIncomingURL);
+      });
+    }
+    const initialURL = await ingress.getInitialURL?.();
+    const userNavigated = history.location.key !== startKey || history.index !== startIndex;
+    if (!userNavigated && initialURL) {
+      const nextPath = mapURLToPath(initialURL);
+      if (nextPath) {
+        applyPath(nextPath, "replace");
+      }
+    }
+  };
+  return {
+    ...adapter,
+    push: (path, title) => {
+      if (parseHistoryPath(path).path === history.location.path) {
+        return;
+      }
+      adapter.push?.(path, title);
+    },
+    replace: (path, title) => {
+      if (parseHistoryPath(path).path === history.location.path) {
+        return;
+      }
+      adapter.replace?.(path, title);
+    },
+    subscribe: (listener) => {
+      subscribers += 1;
+      if (subscribers === 1) {
+        void startIngress();
+      }
+      const unlisten = adapter.subscribe(listener);
+      return () => {
+        unlisten();
+        subscribers = Math.max(0, subscribers - 1);
+        if (subscribers === 0 && stopIngress) {
+          stopIngress();
+          stopIngress = void 0;
+          started = false;
+        }
+      };
+    }
+  };
+};
+var createUniversalAdapter = (options = {}) => {
+  const { strategy = "auto", initialPath = "/", ingress } = options;
+  if (strategy === "web") {
+    return createBrowserRouteAdapter();
+  }
+  if (strategy === "native") {
+    return createNativeRouteAdapter(initialPath, ingress);
+  }
+  return canUseBrowserHistory() ? createBrowserRouteAdapter() : createNativeRouteAdapter(initialPath, ingress);
+};
 var createManualRouteAdapter = (initialPath = "/") => {
   let currentPath = initialPath;
   const listeners = /* @__PURE__ */ new Set();
@@ -747,6 +935,10 @@ var createManualRouteAdapter = (initialPath = "/") => {
     updatePath
   };
 };
+var isDevelopmentMode = () => {
+  const env = globalThis?.process?.env?.NODE_ENV;
+  return env !== "production";
+};
 var buildQueryString = (query = {}) => {
   const parts = [];
   for (const [key, rawValue] of Object.entries(query)) {
@@ -788,6 +980,50 @@ var {
   Consumer: RouteContextConsumer
 } = RouteContext;
 var useRouteContext = () => useContext(RouteContext);
+var getWindow2 = () => {
+  if (typeof globalThis === "undefined") {
+    return void 0;
+  }
+  if ("window" in globalThis) {
+    return globalThis.window;
+  }
+  return void 0;
+};
+var useBrowserLinkInterceptor = (adapter) => {
+  useEffect(() => {
+    const WINDOW = getWindow2();
+    if (!WINDOW || !adapter?.push) {
+      return void 0;
+    }
+    const handleAnchorClick = (event) => {
+      let target = event.target;
+      while (target && target.nodeName !== "A") {
+        target = target.parentNode;
+      }
+      if (!target || target.nodeName !== "A") {
+        return;
+      }
+      const anchor = target;
+      const href = anchor.getAttribute("href");
+      const title = anchor.getAttribute("title") ?? "";
+      if (!href) {
+        return;
+      }
+      try {
+        new URL(href);
+        return;
+      } catch (error) {
+        const nextPath = resolvePath(WINDOW.location?.pathname ?? "", href);
+        event.preventDefault();
+        adapter.push?.(nextPath, title);
+      }
+    };
+    WINDOW.document?.addEventListener("click", handleAnchorClick);
+    return () => {
+      WINDOW.document?.removeEventListener("click", handleAnchorClick);
+    };
+  }, [adapter]);
+};
 var RouteProvider = ({
   adapter,
   initialPath,
@@ -813,11 +1049,11 @@ var RouteProvider = ({
   );
   return /* @__PURE__ */ jsx(RouteContextProvider, { value: contextValue, children });
 };
-var Route = ({
+var RouteMatcher = ({
   /**
    * Use `:` as the first character to denote a parameter in the path.
    */
-  path = "",
+  path,
   onParamsChange,
   exact = false,
   children
@@ -864,23 +1100,56 @@ var Route = ({
   }, [params, onParamsChange]);
   return newParams ? /* @__PURE__ */ jsx(RouteContextProvider, { value: newRouteContext, children }) : null;
 };
-
-// src/app/utils/RouteHistory.ts
-var createRouteAdapterFromHistory = (history) => {
-  return {
-    getPath: () => history.location.path,
-    subscribe: (listener) => {
-      return history.listen((location) => {
-        listener(location.path);
-      });
-    },
-    push: (path) => {
-      history.push(path, { replaceSearch: true });
-    },
-    replace: (path) => {
-      history.replace(path, { replaceSearch: true });
+var RouteRootProvider = ({
+  children,
+  adapter,
+  initialPath,
+  ingress
+}) => {
+  const routeContext = useRouteContext();
+  const autoAdapterRef = useRef(null);
+  if (typeof routeContext.adapter !== "undefined" && isDevelopmentMode()) {
+    throw new Error(
+      "Route provider mode is root-only. Nested Route requires a path."
+    );
+  }
+  if (!autoAdapterRef.current) {
+    autoAdapterRef.current = adapter ?? createUniversalAdapter({ initialPath, ingress });
+  }
+  useBrowserLinkInterceptor(autoAdapterRef.current);
+  return /* @__PURE__ */ jsx(RouteProvider, { adapter: autoAdapterRef.current, initialPath, children });
+};
+var Route = (props) => {
+  if (typeof props.path === "undefined") {
+    if ((typeof props.exact !== "undefined" || typeof props.onParamsChange !== "undefined") && isDevelopmentMode()) {
+      throw new Error(
+        "Route provider mode does not support matcher props. Set a path to use matcher behavior."
+      );
     }
-  };
+    return /* @__PURE__ */ jsx(
+      RouteRootProvider,
+      {
+        adapter: props.adapter,
+        initialPath: props.initialPath,
+        ingress: props.ingress,
+        children: props.children
+      }
+    );
+  }
+  if ((typeof props.initialPath !== "undefined" || typeof props.adapter !== "undefined" || typeof props.ingress !== "undefined") && isDevelopmentMode()) {
+    throw new Error(
+      "Route matcher mode does not support provider props. Remove initialPath/adapter/ingress or use a root Route without path."
+    );
+  }
+  return /* @__PURE__ */ jsx(
+    RouteMatcher,
+    {
+      path: props.path,
+      onParamsChange: props.onParamsChange,
+      exact: props.exact,
+      children: props.children
+    }
+  );
 };
 
 // src/common/IdGeneration/getSimpleId.ts
@@ -1383,4 +1652,4 @@ var useFormEngine = (initialValues = {}, typeInfo, options) => {
   };
 };
 
-export { ApplicationStateContext, ApplicationStateProvider, Route, RouteContext, RouteContextConsumer, RouteContextProvider, RouteProvider, TypeInfoORMClient, buildHistoryPath, buildQueryString, buildRoutePath, computeAreaBounds, computeTrackPixels, createAutoField, createEasyLayout, createFormRenderer, createManualRouteAdapter, createMemoryHistory, createRouteAdapterFromHistory, getApplicationStateIdentifier, getApplicationStateModified, getApplicationStateValue, getApplicationStateValueStructure, getChangedDependencyIndexes, getEasyLayoutTemplateDetails, getFieldKind, getFullUrl, getPascalCaseAreaName, handleRequest, mergeSuites, parseHistoryPath, parseTemplate, requestHandlerFactory, resolveSuite, sendServiceRequest, setApplicationStateModified, setApplicationStateValue, useApplicationStateLoader, useApplicationStateValue, useApplicationStateValueStructure, useController, useDebugDependencies, useFormEngine, useRouteContext, useTypeInfoORMAPI, validateAreas, withRendererOverride };
+export { ApplicationStateContext, ApplicationStateProvider, Route, RouteContext, RouteContextConsumer, RouteContextProvider, RouteProvider, TypeInfoORMClient, buildHistoryPath, buildQueryString, buildRoutePath, canUseBrowserHistory, computeAreaBounds, computeTrackPixels, createAutoField, createBrowserRouteAdapter, createEasyLayout, createFormRenderer, createManualRouteAdapter, createMemoryHistory, createNativeRouteAdapter, createRouteAdapterFromHistory, createUniversalAdapter, getApplicationStateIdentifier, getApplicationStateModified, getApplicationStateValue, getApplicationStateValueStructure, getChangedDependencyIndexes, getEasyLayoutTemplateDetails, getFieldKind, getFullUrl, getPascalCaseAreaName, handleRequest, mergeSuites, parseHistoryPath, parseTemplate, requestHandlerFactory, resolveSuite, sendServiceRequest, setApplicationStateModified, setApplicationStateValue, useApplicationStateLoader, useApplicationStateValue, useApplicationStateValueStructure, useController, useDebugDependencies, useFormEngine, useRouteContext, useTypeInfoORMAPI, validateAreas, withRendererOverride };

package/app/utils/Route.d.ts

@@ -2,9 +2,10 @@
  * @packageDocumentation
  *
  * Render-agnostic routing helpers with nested Route contexts.
- * Supply a RouteAdapter via RouteProvider or a platform-specific wrapper.
+ * Supply a RouteAdapter via RouteProvider or use root Route provider mode.
  */
 import React, { PropsWithChildren } from "react";
+import { type UniversalRouteIngress } from "./UniversalRouteAdapter";
 /**
  * Platform adapter that supplies the current path and change notifications.
  */
@@ -119,11 +120,17 @@ export type RouteProps<ParamsType extends Record<string, any>> = {
      * Require an exact match for the route path.
      */
     exact?: boolean;
+    /**
+     * Optional initial path override for root provider mode only.
+     */
+    initialPath?: string;
+    /**
+     * Optional adapter override for root provider mode only.
+     */
+    adapter?: RouteAdapter;
+    /**
+     * Optional external URL ingress for root provider mode only.
+     */
+    ingress?: UniversalRouteIngress;
 };
-/**
- * Organize nested routes with parameters.
- *
- * @typeParam ParamsType - Param shape for this route.
- * @param props - Route props including path, params handler, and children.
- */
-export declare const Route: <ParamsType extends Record<string, any>>({ path, onParamsChange, exact, children, }: PropsWithChildren<RouteProps<ParamsType>>) => import("react/jsx-runtime").JSX.Element | null;
+export declare const Route: <ParamsType extends Record<string, any>>(props: PropsWithChildren<RouteProps<ParamsType>>) => import("react/jsx-runtime").JSX.Element;

package/app/utils/UniversalRouteAdapter.d.ts

@@ -0,0 +1,73 @@
+import type { RouteAdapter } from "./Route";
+/**
+ * Runtime strategy for universal route adapters.
+ */
+export type UniversalRouteStrategy = "auto" | "web" | "native";
+/**
+ * Options for {@link createUniversalAdapter}.
+ */
+export type CreateUniversalAdapterOptions = {
+    /**
+     * Runtime strategy selection.
+     *
+     * - `"auto"`: use web when DOM + History API exist, else native.
+     * - `"web"`: force browser history.
+     * - `"native"`: force in-memory history.
+     *
+     * Default: `"auto"`.
+     */
+    strategy?: UniversalRouteStrategy;
+    /**
+     * Initial path used by native strategy memory history.
+     *
+     * Default: `"/"`.
+     */
+    initialPath?: string;
+    /**
+     * Optional ingress hook for native strategy.
+     *
+     * Use this to bridge deep-link systems into the adapter.
+     */
+    ingress?: UniversalRouteIngress;
+};
+/**
+ * Ingress hook for applying external URLs/paths to native strategy.
+ */
+export type UniversalRouteIngress = {
+    /**
+     * Optional initial URL/path provider.
+     */
+    getInitialURL?: () => Promise<string | null | undefined> | string | null | undefined;
+    /**
+     * Optional URL/path event subscription.
+     */
+    subscribe?: (listener: (url: string) => void) => () => void;
+    /**
+     * Incoming event application mode.
+     *
+     * Default: `"replace"`.
+     */
+    onIncomingURL?: "push" | "replace";
+    /**
+     * Optional mapper converting URL -> route path.
+     *
+     * Default maps using shared history path parsing.
+     */
+    mapURLToPath?: (url: string) => string;
+};
+/**
+ * Detect whether browser history is available at runtime.
+ */
+export declare const canUseBrowserHistory: () => boolean;
+/**
+ * Create a browser RouteAdapter backed by the History API.
+ */
+export declare const createBrowserRouteAdapter: () => RouteAdapter;
+/**
+ * Create an in-memory RouteAdapter for non-DOM runtimes.
+ */
+export declare const createNativeRouteAdapter: (initialPath?: string, ingress?: UniversalRouteIngress) => RouteAdapter;
+/**
+ * Create a runtime-selected RouteAdapter for web/native environments.
+ */
+export declare const createUniversalAdapter: (options?: CreateUniversalAdapterOptions) => RouteAdapter;

package/app/utils/index.d.ts

@@ -18,6 +18,7 @@ export * from "./easy-layout";
 export * from "./History";
 export * from "./Route";
 export * from "./RouteHistory";
+export * from "./UniversalRouteAdapter";
 export * from "./Service";
 export * from "./TypeInfoORMAPIUtils";
 export * from "./TypeInfoORMClient";

package/native/index.js

@@ -1,5 +1,5 @@
-import { createContext, useContext, createElement, useState, useEffect, useMemo, useRef } from 'react';
-import { jsx } from 'react/jsx-runtime';
+import { createContext, createElement, useMemo } from 'react';
+import 'react/jsx-runtime';
 
 var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
   get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
@@ -485,206 +485,6 @@ var createNativeFormRenderer = (options) => {
   });
 };
 
-// src/common/Routing.ts
-var PATH_DELIMITER = "/";
-var getPotentialJSONValue = (value) => {
-  try {
-    return JSON.parse(value);
-  } catch (error) {
-    return value;
-  }
-};
-var getPathArray = (path, delimiter = PATH_DELIMITER, filterEmptyOutput = false, filterEmptyInput = true, useJson = true, uriDecodeParts = true) => path.split(delimiter).filter(filterEmptyInput ? (p) => p !== "" : () => true).map(uriDecodeParts ? decodeURIComponent : (x) => x).map(useJson ? getPotentialJSONValue : (p) => p).filter(filterEmptyOutput ? (p) => p ?? false : () => true);
-var getPathString = (parts = [], delimiter = PATH_DELIMITER, filterEmptyInput = false, useJson = true, uriEncodeParts = false) => parts.filter(filterEmptyInput ? (p) => p ?? false : () => true).map(useJson ? (p) => JSON.stringify(p) : (x) => x).map(uriEncodeParts ? encodeURIComponent : (x) => x).join(delimiter);
-var mergeStringPaths = (path1, path2, delimiter = PATH_DELIMITER, filterEmptyOutput = false, filterEmptyInput = true, useJson = true, uriEncodeParts = false) => getPathString(
-  [
-    ...getPathArray(
-      path1,
-      delimiter,
-      filterEmptyOutput,
-      filterEmptyInput,
-      useJson,
-      uriEncodeParts
-    ),
-    ...getPathArray(
-      path2,
-      delimiter,
-      filterEmptyOutput,
-      filterEmptyInput,
-      useJson,
-      uriEncodeParts
-    )
-  ],
-  delimiter,
-  filterEmptyInput,
-  useJson,
-  uriEncodeParts
-);
-var getParamsAndTestPath = (path, testPath, exact = false) => {
-  const pathList = getPathArray(path);
-  const testPathList = getPathArray(testPath);
-  if (exact && pathList.length !== testPathList.length) {
-    return false;
-  } else {
-    let params = {};
-    if (pathList.length >= testPathList.length) {
-      for (let i = 0; i < testPathList.length; i++) {
-        const testPathPart = testPathList[i];
-        const pathPart = pathList[i];
-        if (testPathPart.startsWith(":")) {
-          const paramName = testPathPart.slice(1);
-          params[paramName] = pathPart;
-        } else if (pathPart !== testPathPart) {
-          return false;
-        }
-      }
-    } else {
-      return false;
-    }
-    return params;
-  }
-};
-var createManualRouteAdapter = (initialPath = "/") => {
-  let currentPath = initialPath;
-  const listeners = /* @__PURE__ */ new Set();
-  const updatePath = (nextPath) => {
-    currentPath = nextPath;
-    listeners.forEach((listener) => listener(nextPath));
-  };
-  const adapter = {
-    getPath: () => currentPath,
-    subscribe: (listener) => {
-      listeners.add(listener);
-      return () => {
-        listeners.delete(listener);
-      };
-    },
-    push: (path) => updatePath(path),
-    replace: (path) => updatePath(path)
-  };
-  return {
-    adapter,
-    updatePath
-  };
-};
-var buildQueryString = (query = {}) => {
-  const parts = [];
-  for (const [key, rawValue] of Object.entries(query)) {
-    if (rawValue === void 0) {
-      continue;
-    }
-    const values = Array.isArray(rawValue) ? rawValue : [rawValue];
-    for (const value of values) {
-      if (value === void 0) {
-        continue;
-      }
-      const encodedKey = encodeURIComponent(key);
-      const encodedValue = value === null ? "" : encodeURIComponent(String(value));
-      parts.push(`${encodedKey}=${encodedValue}`);
-    }
-  }
-  return parts.join("&");
-};
-var buildRoutePath = (segments, query) => {
-  const normalizedSegments = segments.map((segment) => String(segment));
-  const basePath = "/" + getPathString(normalizedSegments, "/", true, false, true);
-  const queryString = query ? buildQueryString(query) : "";
-  return queryString ? `${basePath}?${queryString}` : basePath;
-};
-var RouteContext = createContext({
-  currentWindowPath: "",
-  parentPath: "",
-  params: {},
-  isTopLevel: true
-});
-var {
-  /**
-   * @ignore
-   */
-  Provider: RouteContextProvider,
-  /**
-   * @ignore
-   */
-  Consumer: RouteContextConsumer
-} = RouteContext;
-var useRouteContext = () => useContext(RouteContext);
-var RouteProvider = ({
-  adapter,
-  initialPath,
-  children
-}) => {
-  const [currentPath, setCurrentPath] = useState(
-    initialPath ?? adapter.getPath()
-  );
-  useEffect(() => {
-    return adapter.subscribe((nextPath) => {
-      setCurrentPath(nextPath);
-    });
-  }, [adapter]);
-  const contextValue = useMemo(
-    () => ({
-      currentWindowPath: currentPath,
-      parentPath: "",
-      params: {},
-      isTopLevel: true,
-      adapter
-    }),
-    [currentPath, adapter]
-  );
-  return /* @__PURE__ */ jsx(RouteContextProvider, { value: contextValue, children });
-};
-var Route = ({
-  /**
-   * Use `:` as the first character to denote a parameter in the path.
-   */
-  path = "",
-  onParamsChange,
-  exact = false,
-  children
-}) => {
-  const {
-    currentWindowPath = "",
-    parentPath = "",
-    params: parentParams = {},
-    adapter
-  } = useRouteContext();
-  const targetCurrentPath = useMemo(
-    () => currentWindowPath,
-    [currentWindowPath]
-  );
-  const fullPath = useMemo(
-    () => mergeStringPaths(parentPath, path),
-    [parentPath, path]
-  );
-  const newParams = useMemo(
-    () => getParamsAndTestPath(targetCurrentPath, fullPath, exact),
-    [targetCurrentPath, fullPath, exact]
-  );
-  const params = useMemo(
-    () => ({
-      ...parentParams,
-      ...newParams ? newParams : {}
-    }),
-    [parentParams, newParams]
-  );
-  const newRouteContext = useMemo(
-    () => ({
-      currentWindowPath: targetCurrentPath,
-      parentPath: fullPath,
-      params,
-      isTopLevel: false,
-      adapter
-    }),
-    [targetCurrentPath, fullPath, params, adapter]
-  );
-  useEffect(() => {
-    if (onParamsChange) {
-      onParamsChange(params);
-    }
-  }, [params, onParamsChange]);
-  return newParams ? /* @__PURE__ */ jsx(RouteContextProvider, { value: newRouteContext, children }) : null;
-};
-
 // src/app/utils/History.ts
 var ensurePrefix = (value, prefix) => value ? value.startsWith(prefix) ? value : `${prefix}${value}` : "";
 var parseHistoryPath = (inputPath) => {
@@ -1188,7 +988,19 @@ var createNativeHistory = (options = {}) => {
       const startKey = history.location.key;
       const startIndex = history.index;
       unsubscribe = adapter.subscribe((url) => {
-        applyIncomingURL(url);
+        const targetPath = mapURLToPath(url);
+        if (!targetPath) {
+          return;
+        }
+        const userNavigated = history.location.key !== startKey || history.index !== startIndex;
+        if (userNavigated && targetPath === initialPath) {
+          return;
+        }
+        if (onIncomingURL === "push") {
+          history.push(targetPath, { replaceSearch: true });
+        } else {
+          history.replace(targetPath, { replaceSearch: true });
+        }
       });
       const initialURL = await adapter.getInitialURL();
       if (history.location.key === startKey && history.index === startIndex) {
@@ -1220,56 +1032,57 @@ var createNativeBackHandler = (history) => {
   };
 };
 
-// src/app/utils/RouteHistory.ts
-var createRouteAdapterFromHistory = (history) => {
-  return {
-    getPath: () => history.location.path,
-    subscribe: (listener) => {
-      return history.listen((location) => {
-        listener(location.path);
-      });
-    },
-    push: (path) => {
-      history.push(path, { replaceSearch: true });
-    },
-    replace: (path) => {
-      history.replace(path, { replaceSearch: true });
-    }
-  };
-};
-var NativeRouteProvider = ({
-  children,
-  history,
-  ...historyOptions
-}) => {
-  const historyRef = useRef(history ?? null);
-  if (!historyRef.current) {
-    historyRef.current = createNativeHistory(historyOptions);
+// src/common/Routing.ts
+var PATH_DELIMITER = "/";
+var getPotentialJSONValue = (value) => {
+  try {
+    return JSON.parse(value);
+  } catch (error) {
+    return value;
   }
-  const adapterRef = useRef(createRouteAdapterFromHistory(historyRef.current));
-  useEffect(() => {
-    const targetHistory = historyRef.current;
-    if (!targetHistory) {
-      return;
-    }
-    void targetHistory.start();
-    return () => {
-      targetHistory.stop();
-    };
-  }, []);
-  return /* @__PURE__ */ jsx(RouteProvider, { adapter: adapterRef.current, children });
 };
-var NativeRoute = (props) => {
-  const routeContext = useRouteContext();
-  const hasAdapter = useMemo(
-    () => typeof routeContext.adapter !== "undefined",
-    [routeContext.adapter]
-  );
-  if (hasAdapter) {
-    return /* @__PURE__ */ jsx(Route, { ...props });
+var getPathArray = (path, delimiter = PATH_DELIMITER, filterEmptyOutput = false, filterEmptyInput = true, useJson = true, uriDecodeParts = true) => path.split(delimiter).filter(filterEmptyInput ? (p) => p !== "" : () => true).map(uriDecodeParts ? decodeURIComponent : (x) => x).map(useJson ? getPotentialJSONValue : (p) => p).filter(filterEmptyOutput ? (p) => p ?? false : () => true);
+var getPathString = (parts = [], delimiter = PATH_DELIMITER, filterEmptyInput = false, useJson = true, uriEncodeParts = false) => parts.filter(filterEmptyInput ? (p) => p ?? false : () => true).map(useJson ? (p) => JSON.stringify(p) : (x) => x).map(uriEncodeParts ? encodeURIComponent : (x) => x).join(delimiter);
+var buildQueryString = (query = {}) => {
+  const parts = [];
+  for (const [key, rawValue] of Object.entries(query)) {
+    if (rawValue === void 0) {
+      continue;
+    }
+    const values = Array.isArray(rawValue) ? rawValue : [rawValue];
+    for (const value of values) {
+      if (value === void 0) {
+        continue;
+      }
+      const encodedKey = encodeURIComponent(key);
+      const encodedValue = value === null ? "" : encodeURIComponent(String(value));
+      parts.push(`${encodedKey}=${encodedValue}`);
+    }
   }
-  return /* @__PURE__ */ jsx(NativeRouteProvider, { children: /* @__PURE__ */ jsx(Route, { ...props }) });
+  return parts.join("&");
 };
+var buildRoutePath = (segments, query) => {
+  const normalizedSegments = segments.map((segment) => String(segment));
+  const basePath = "/" + getPathString(normalizedSegments, "/", true, false, true);
+  const queryString = query ? buildQueryString(query) : "";
+  return queryString ? `${basePath}?${queryString}` : basePath;
+};
+var RouteContext = createContext({
+  currentWindowPath: "",
+  parentPath: "",
+  params: {},
+  isTopLevel: true
+});
+var {
+  /**
+   * @ignore
+   */
+  Provider: RouteContextProvider,
+  /**
+   * @ignore
+   */
+  Consumer: RouteContextConsumer
+} = RouteContext;
 
 // src/native/utils/Route.ts
 var createNavigationStateRouteAdapter = (options) => {
@@ -1308,4 +1121,4 @@ var buildPathFromRouteChain = (routeChain, config, query) => {
   return buildRoutePath(segments, query);
 };
 
-export { ArrayContainer, ArrayItemWrapper, Button, ErrorMessage, FieldWrapper, NativeEasyLayoutView, NativeRoute, NativeRouteProvider, Route, RouteContext, RouteContextConsumer, RouteContextProvider, RouteProvider, buildHistoryPath, buildPathFromRouteChain, buildQueryString, buildRoutePath, createManualRouteAdapter, createMemoryHistory, createNativeBackHandler, createNativeFormRenderer, createNativeHistory, createNavigationStateRouteAdapter, makeNativeEasyLayout, mapNativeURLToPath, nativeAutoField, nativeSuite, parseHistoryPath, useNativeEasyLayout, useRouteContext };
+export { ArrayContainer, ArrayItemWrapper, Button, ErrorMessage, FieldWrapper, NativeEasyLayoutView, buildHistoryPath, buildPathFromRouteChain, createMemoryHistory, createNativeBackHandler, createNativeFormRenderer, createNativeHistory, createNavigationStateRouteAdapter, makeNativeEasyLayout, mapNativeURLToPath, nativeAutoField, nativeSuite, parseHistoryPath, useNativeEasyLayout };

package/native/utils/index.d.ts

@@ -3,9 +3,7 @@
  *
  * Native (render-agnostic) utilities.
  */
-export * from "../../app/utils/Route";
 export * from "../../app/utils/History";
 export * from "./EasyLayout";
 export * from "./History";
-export * from "./NativeRoute";
 export * from "./Route";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@resistdesign/voltra",
-  "version": "3.0.0-alpha.20",
+  "version": "3.0.0-alpha.22",
   "description": "With our powers combined!",
   "homepage": "https://voltra.app",
   "repository": "git@github.com:resistdesign/voltra.git",

package/web/index.js

@@ -1,7 +1,7 @@
 import * as styledBase from 'styled-components';
 import styledBase__default from 'styled-components';
 import { jsxs, jsx, Fragment } from 'react/jsx-runtime';
-import { createContext, useContext, useEffect, useRef, useMemo, useState, useCallback } from 'react';
+import { useEffect, useState, useCallback, useMemo } from 'react';
 
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -1018,280 +1018,4 @@ var getEasyLayout = (extendFrom, areasExtendFrom, options = {}) => {
   return createEasyLayout(styledFactory, extendFrom, areasExtendFrom, options);
 };
 
-// src/common/Routing.ts
-var PATH_DELIMITER = "/";
-var getPotentialJSONValue = (value) => {
-  try {
-    return JSON.parse(value);
-  } catch (error) {
-    return value;
-  }
-};
-var getPathArray = (path, delimiter = PATH_DELIMITER, filterEmptyOutput = false, filterEmptyInput = true, useJson = true, uriDecodeParts = true) => path.split(delimiter).filter(filterEmptyInput ? (p) => p !== "" : () => true).map(uriDecodeParts ? decodeURIComponent : (x) => x).map(useJson ? getPotentialJSONValue : (p) => p).filter(filterEmptyOutput ? (p) => p ?? false : () => true);
-var getPathString = (parts = [], delimiter = PATH_DELIMITER, filterEmptyInput = false, useJson = true, uriEncodeParts = false) => parts.filter(filterEmptyInput ? (p) => p ?? false : () => true).map(useJson ? (p) => JSON.stringify(p) : (x) => x).map(uriEncodeParts ? encodeURIComponent : (x) => x).join(delimiter);
-var mergeStringPaths = (path1, path2, delimiter = PATH_DELIMITER, filterEmptyOutput = false, filterEmptyInput = true, useJson = true, uriEncodeParts = false) => getPathString(
-  [
-    ...getPathArray(
-      path1,
-      delimiter,
-      filterEmptyOutput,
-      filterEmptyInput,
-      useJson,
-      uriEncodeParts
-    ),
-    ...getPathArray(
-      path2,
-      delimiter,
-      filterEmptyOutput,
-      filterEmptyInput,
-      useJson,
-      uriEncodeParts
-    )
-  ],
-  delimiter,
-  filterEmptyInput,
-  useJson,
-  uriEncodeParts
-);
-var resolvePath = (currentPath, newPath) => {
-  const newSegments = getPathArray(newPath, PATH_DELIMITER, true);
-  let currentSegments = getPathArray(currentPath, PATH_DELIMITER, true);
-  if (newPath.startsWith("/")) {
-    currentSegments = [];
-  }
-  newSegments.forEach((segment) => {
-    if (segment === "..") {
-      if (currentSegments.length > 0) {
-        currentSegments.pop();
-      }
-    } else if (segment !== ".") {
-      currentSegments.push(segment);
-    }
-  });
-  return "/" + currentSegments.join("/");
-};
-var getParamsAndTestPath = (path, testPath, exact = false) => {
-  const pathList = getPathArray(path);
-  const testPathList = getPathArray(testPath);
-  if (exact && pathList.length !== testPathList.length) {
-    return false;
-  } else {
-    let params = {};
-    if (pathList.length >= testPathList.length) {
-      for (let i = 0; i < testPathList.length; i++) {
-        const testPathPart = testPathList[i];
-        const pathPart = pathList[i];
-        if (testPathPart.startsWith(":")) {
-          const paramName = testPathPart.slice(1);
-          params[paramName] = pathPart;
-        } else if (pathPart !== testPathPart) {
-          return false;
-        }
-      }
-    } else {
-      return false;
-    }
-    return params;
-  }
-};
-var RouteContext = createContext({
-  currentWindowPath: "",
-  parentPath: "",
-  params: {},
-  isTopLevel: true
-});
-var {
-  /**
-   * @ignore
-   */
-  Provider: RouteContextProvider,
-  /**
-   * @ignore
-   */
-  Consumer: RouteContextConsumer
-} = RouteContext;
-var useRouteContext = () => useContext(RouteContext);
-var RouteProvider = ({
-  adapter,
-  initialPath,
-  children
-}) => {
-  const [currentPath, setCurrentPath] = useState(
-    initialPath ?? adapter.getPath()
-  );
-  useEffect(() => {
-    return adapter.subscribe((nextPath) => {
-      setCurrentPath(nextPath);
-    });
-  }, [adapter]);
-  const contextValue = useMemo(
-    () => ({
-      currentWindowPath: currentPath,
-      parentPath: "",
-      params: {},
-      isTopLevel: true,
-      adapter
-    }),
-    [currentPath, adapter]
-  );
-  return /* @__PURE__ */ jsx(RouteContextProvider, { value: contextValue, children });
-};
-var Route = ({
-  /**
-   * Use `:` as the first character to denote a parameter in the path.
-   */
-  path = "",
-  onParamsChange,
-  exact = false,
-  children
-}) => {
-  const {
-    currentWindowPath = "",
-    parentPath = "",
-    params: parentParams = {},
-    adapter
-  } = useRouteContext();
-  const targetCurrentPath = useMemo(
-    () => currentWindowPath,
-    [currentWindowPath]
-  );
-  const fullPath = useMemo(
-    () => mergeStringPaths(parentPath, path),
-    [parentPath, path]
-  );
-  const newParams = useMemo(
-    () => getParamsAndTestPath(targetCurrentPath, fullPath, exact),
-    [targetCurrentPath, fullPath, exact]
-  );
-  const params = useMemo(
-    () => ({
-      ...parentParams,
-      ...newParams ? newParams : {}
-    }),
-    [parentParams, newParams]
-  );
-  const newRouteContext = useMemo(
-    () => ({
-      currentWindowPath: targetCurrentPath,
-      parentPath: fullPath,
-      params,
-      isTopLevel: false,
-      adapter
-    }),
-    [targetCurrentPath, fullPath, params, adapter]
-  );
-  useEffect(() => {
-    if (onParamsChange) {
-      onParamsChange(params);
-    }
-  }, [params, onParamsChange]);
-  return newParams ? /* @__PURE__ */ jsx(RouteContextProvider, { value: newRouteContext, children }) : null;
-};
-var getWindow = () => {
-  if (typeof globalThis === "undefined") {
-    return void 0;
-  }
-  if ("window" in globalThis) {
-    return globalThis.window;
-  }
-  return void 0;
-};
-var createBrowserRouteAdapter = () => {
-  const WINDOW = getWindow();
-  const listeners = /* @__PURE__ */ new Set();
-  const notify = () => {
-    const path = WINDOW?.location?.pathname ?? "";
-    listeners.forEach((listener) => listener(path));
-  };
-  const handlePopState = () => {
-    notify();
-  };
-  const subscribe = (listener) => {
-    listeners.add(listener);
-    if (WINDOW) {
-      WINDOW.addEventListener("popstate", handlePopState);
-      WINDOW.addEventListener("statechanged", handlePopState);
-    }
-    return () => {
-      listeners.delete(listener);
-      if (WINDOW) {
-        WINDOW.removeEventListener("popstate", handlePopState);
-        WINDOW.removeEventListener("statechanged", handlePopState);
-      }
-    };
-  };
-  return {
-    getPath: () => WINDOW?.location?.pathname ?? "",
-    subscribe,
-    push: (path, title = "") => {
-      if (!WINDOW?.history) {
-        return;
-      }
-      WINDOW.history.pushState({}, title, path);
-      notify();
-    },
-    replace: (path, title = "") => {
-      if (!WINDOW?.history?.replaceState) {
-        return;
-      }
-      WINDOW.history.replaceState({}, title, path);
-      notify();
-    }
-  };
-};
-var useBrowserLinkInterceptor = (adapter) => {
-  useEffect(() => {
-    const WINDOW = getWindow();
-    if (!WINDOW || !adapter?.push) {
-      return void 0;
-    }
-    const handleAnchorClick = (event) => {
-      let target = event.target;
-      while (target && target.nodeName !== "A") {
-        target = target.parentNode;
-      }
-      if (!target || target.nodeName !== "A") {
-        return;
-      }
-      const anchor = target;
-      const href = anchor.getAttribute("href");
-      const title = anchor.getAttribute("title") ?? "";
-      if (!href) {
-        return;
-      }
-      try {
-        new URL(href);
-        return;
-      } catch (error) {
-        const nextPath = resolvePath(WINDOW.location?.pathname ?? "", href);
-        event.preventDefault();
-        adapter.push?.(nextPath, title);
-      }
-    };
-    WINDOW.document.addEventListener("click", handleAnchorClick);
-    return () => {
-      WINDOW.document.removeEventListener("click", handleAnchorClick);
-    };
-  }, [adapter]);
-};
-var RouteProvider2 = ({ children }) => {
-  const adapterRef = useRef(null);
-  if (!adapterRef.current) {
-    adapterRef.current = createBrowserRouteAdapter();
-  }
-  useBrowserLinkInterceptor(adapterRef.current);
-  return /* @__PURE__ */ jsx(RouteProvider, { adapter: adapterRef.current, children });
-};
-var Route2 = (props) => {
-  const routeContext = useRouteContext();
-  const hasAdapter = useMemo(
-    () => typeof routeContext.adapter !== "undefined",
-    [routeContext.adapter]
-  );
-  if (hasAdapter) {
-    return /* @__PURE__ */ jsx(Route, { ...props });
-  }
-  return /* @__PURE__ */ jsx(RouteProvider2, { children: /* @__PURE__ */ jsx(Route, { ...props }) });
-};
-
-export { ArrayContainer, ArrayItemWrapper, AutoField, AutoForm, AutoFormView, ErrorMessage, FieldWrapper, Route2 as Route, RouteProvider2 as RouteProvider, createBrowserRouteAdapter, createWebFormRenderer, getEasyLayout, useRouteContext, webAutoField, webSuite };
+export { ArrayContainer, ArrayItemWrapper, AutoField, AutoForm, AutoFormView, ErrorMessage, FieldWrapper, createWebFormRenderer, getEasyLayout, webAutoField, webSuite };

package/web/utils/Route.d.ts

@@ -1,20 +1,14 @@
 /**
  * @packageDocumentation
  *
- * Web (DOM) routing helpers that wire the app-level Route to browser history.
+ * Web routing exports unified app Route implementation.
  */
 import { PropsWithChildren } from "react";
-import { type RouteAdapter, type RouteProps, useRouteContext } from "../../app/utils/Route";
+import { Route, useRouteContext } from "../../app/utils/Route";
+import { createBrowserRouteAdapter } from "../../app/utils/UniversalRouteAdapter";
 /**
- * Create a browser RouteAdapter backed by the History API.
- */
-export declare const createBrowserRouteAdapter: () => RouteAdapter;
-/**
- * Web RouteProvider using the browser adapter.
+ * Backward-compatible web RouteProvider that auto-creates a browser adapter.
  */
 export declare const RouteProvider: ({ children }: PropsWithChildren) => import("react/jsx-runtime").JSX.Element;
-/**
- * Web Route component that auto-provides the browser adapter at the top level.
- */
-export declare const Route: <ParamsType extends Record<string, any>>(props: PropsWithChildren<RouteProps<ParamsType>>) => import("react/jsx-runtime").JSX.Element;
-export { useRouteContext };
+export { Route, useRouteContext, createBrowserRouteAdapter };
+export type { RouteAdapter, RouteContextType, RouteProps, RouteProviderProps, RouteQuery, RouteQueryValue, } from "../../app/utils/Route";

package/web/utils/index.d.ts

@@ -4,4 +4,3 @@
  * Web-only utilities.
  */
 export * from "./EasyLayout";
-export * from "./Route";

package/native/utils/NativeRoute.d.ts

@@ -1,44 +0,0 @@
-/**
- * @packageDocumentation
- *
- * Native Route wrappers that bridge native history into app Route context.
- */
-import { PropsWithChildren } from "react";
-import { type RouteProps } from "../../app/utils/Route";
-import { type CreateNativeHistoryOptions, type NativeHistoryController } from "./History";
-/**
- * Native route-provider props.
- */
-export type NativeRouteProviderProps = PropsWithChildren<CreateNativeHistoryOptions & {
-    /**
-     * Optional externally managed history instance.
-     *
-     * When provided, `CreateNativeHistoryOptions` are ignored for construction
-     * and the provider will use this instance directly.
-     */
-    history?: NativeHistoryController;
-}>;
-/**
- * Native RouteProvider that starts/stops native history lifecycle automatically.
- *
- * Behavior:
- * - If `history` is provided, it is used as-is.
- * - Otherwise, a history instance is created once from options.
- * - On mount: calls `history.start()`.
- * - On unmount: calls `history.stop()`.
- *
- * Example:
- * ```tsx
- * <NativeRouteProvider adapter={linkingAdapter}>
- *   <NativeRoute path="/app" />
- * </NativeRouteProvider>
- * ```
- */
-export declare const NativeRouteProvider: ({ children, history, ...historyOptions }: NativeRouteProviderProps) => import("react/jsx-runtime").JSX.Element;
-/**
- * Native Route component that auto-provides native history at the top level.
- *
- * If a route adapter already exists in context, this renders the core route
- * directly. Otherwise it creates a top-level {@link NativeRouteProvider}.
- */
-export declare const NativeRoute: <ParamsType extends Record<string, any>>(props: PropsWithChildren<RouteProps<ParamsType>>) => import("react/jsx-runtime").JSX.Element;