one 1.2.82 → 1.2.84

package/src/router/routeMask.ts

@@ -0,0 +1,293 @@
+/**
+ * Configuration for a route mask.
+ * Route masking displays a different URL in the browser than the actual route being rendered.
+ * Uses history.state to store the actual route, so on page reload the router can restore the original route.
+ */
+export interface RouteMaskOptions {
+  /**
+   * The route pattern to match (the actual route being navigated to).
+   * Supports dynamic segments like [id] or $id.
+   *
+   * @example '/photos/[id]/modal' or '/photos/$photoId/modal'
+   */
+  from: string
+
+  /**
+   * The route pattern to display in the browser URL (the masked URL).
+   * Supports dynamic segments that will be populated from the matched params.
+   *
+   * @example '/photos/[id]' or '/photos/$photoId'
+   */
+  to: string
+
+  /**
+   * How to handle parameters when masking.
+   * - `true` (default): Forward all matched params to the masked URL
+   * - `false`: Don't forward any params
+   * - Function: Custom param transformation
+   *
+   * @default true
+   */
+  params?: boolean | ((matchedParams: Record<string, string>) => Record<string, string>)
+
+  /**
+   * If true, unmask when the page is reloaded (show the masked URL's content).
+   * If false (default), keep the actual route on reload (show the original content).
+   *
+   * When false: Reload at /photos/5 → still shows /photos/5/modal content
+   * When true: Reload at /photos/5 → shows /photos/5 content
+   *
+   * @default false
+   */
+  unmaskOnReload?: boolean
+
+  /**
+   * If true, encode the actual route as a base64 postfix in the URL pathname instead of history.state.
+   *
+   * URL will look like: /photos/5__L3Bob3Rvcy81L21vZGFs
+   *
+   * Benefits:
+   * - Server can parse the postfix and render the actual route (no SSR flash)
+   * - URL contains the "truth" about what to render
+   * - Works consistently across SSR, SSG, and SPA
+   * - No query parameter visible
+   *
+   * Tradeoffs:
+   * - URL has a base64 suffix visible after `__`
+   *
+   * @default false
+   */
+  useSearchParam?: boolean
+}
+
+/**
+ * A compiled route mask ready for matching.
+ */
+export interface RouteMask extends RouteMaskOptions {
+  /** Regex pattern for matching the 'from' route */
+  _fromRegex: RegExp
+  /** Parameter names extracted from the 'from' pattern */
+  _fromParams: string[]
+}
+
+/**
+ * Creates a route mask for automatic URL masking during navigation.
+ *
+ * Route masking displays a different URL in the browser than the actual route.
+ * Uses browser history.state to store the actual route, enabling:
+ * - Modal overlays with clean shareable URLs
+ * - Different URL for in-app navigation vs direct access
+ *
+ * @example
+ * ```tsx
+ * import { createRouteMask } from 'one'
+ *
+ * const photoMask = createRouteMask({
+ *   from: '/photos/[id]/modal',
+ *   to: '/photos/[id]',
+ *   params: true,
+ * })
+ *
+ * // In vite.config.ts:
+ * one({
+ *   router: { routeMasks: [photoMask] },
+ * })
+ * ```
+ */
+export function createRouteMask(options: RouteMaskOptions): RouteMask {
+  const {
+    from,
+    to,
+    params = true,
+    unmaskOnReload = false,
+    useSearchParam = false,
+  } = options
+
+  // Extract parameter names and build regex from the 'from' pattern
+  const fromParams: string[] = []
+  const fromRegexStr = from
+    .split('/')
+    .map((segment) => {
+      // Handle catch-all segments [...rest] or $...rest
+      if (segment.startsWith('[...') && segment.endsWith(']')) {
+        const paramName = segment.slice(4, -1)
+        fromParams.push(paramName)
+        return '(.+)'
+      }
+      if (segment.startsWith('$...')) {
+        const paramName = segment.slice(4)
+        fromParams.push(paramName)
+        return '(.+)'
+      }
+      // Handle dynamic segments [id] or $id
+      if (segment.startsWith('[') && segment.endsWith(']')) {
+        const paramName = segment.slice(1, -1)
+        fromParams.push(paramName)
+        return '([^/]+)'
+      }
+      if (segment.startsWith('$')) {
+        const paramName = segment.slice(1)
+        fromParams.push(paramName)
+        return '([^/]+)'
+      }
+      // Static segment - escape regex special chars
+      return segment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    })
+    .join('/')
+
+  return {
+    from,
+    to,
+    params,
+    unmaskOnReload,
+    useSearchParam,
+    _fromRegex: new RegExp(`^${fromRegexStr}$`),
+    _fromParams: fromParams,
+  }
+}
+
+/**
+ * Matches a pathname against a route mask.
+ * Returns the matched params if successful, or null if no match.
+ */
+export function matchRouteMask(
+  pathname: string,
+  mask: RouteMask
+): Record<string, string> | null {
+  const match = pathname.match(mask._fromRegex)
+  if (!match) return null
+
+  const params: Record<string, string> = {}
+  mask._fromParams.forEach((paramName, index) => {
+    params[paramName] = match[index + 1]
+  })
+
+  return params
+}
+
+/**
+ * Builds the masked URL from a route mask and matched params.
+ */
+export function buildMaskedPath(
+  mask: RouteMask,
+  matchedParams: Record<string, string>
+): string {
+  // Determine which params to use
+  let params: Record<string, string>
+  if (mask.params === false) {
+    params = {}
+  } else if (typeof mask.params === 'function') {
+    params = mask.params(matchedParams)
+  } else {
+    params = matchedParams
+  }
+
+  // Build the masked URL by replacing dynamic segments
+  return mask.to
+    .split('/')
+    .map((segment) => {
+      // Handle [...rest] or $...rest
+      if (segment.startsWith('[...') && segment.endsWith(']')) {
+        const paramName = segment.slice(4, -1)
+        return params[paramName] ?? ''
+      }
+      if (segment.startsWith('$...')) {
+        const paramName = segment.slice(4)
+        return params[paramName] ?? ''
+      }
+      // Handle [id] or $id
+      if (segment.startsWith('[') && segment.endsWith(']')) {
+        const paramName = segment.slice(1, -1)
+        return params[paramName] ?? ''
+      }
+      if (segment.startsWith('$')) {
+        const paramName = segment.slice(1)
+        return params[paramName] ?? ''
+      }
+      return segment
+    })
+    .join('/')
+}
+
+/**
+ * URL-safe base64 encode for the _unmask suffix.
+ * Replaces +/= with URL-safe characters so the param looks like an opaque token.
+ */
+export function encodeUnmask(path: string): string {
+  return btoa(path).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
+
+/**
+ * Decode a URL-safe base64 _unmask value back to the original path.
+ */
+export function decodeUnmask(encoded: string): string {
+  const base64 = encoded.replace(/-/g, '+').replace(/_/g, '/')
+  return atob(base64)
+}
+
+/**
+ * The separator used in the pathname postfix for route unmasking.
+ * e.g. /photos/3__L3Bob3Rvcy8zL21vZGFs
+ */
+const UNMASK_SEPARATOR = '__'
+
+/**
+ * Parse the base64-encoded unmask suffix from a pathname.
+ * Looks for `__` separator in the last path segment.
+ * Returns the decoded actual path, or null if no unmask suffix found.
+ *
+ * @example
+ * parseUnmaskFromPath('/photos/3__L3Bob3Rvcy8zL21vZGFs') // '/photos/3/modal'
+ * parseUnmaskFromPath('/photos/3') // null
+ */
+export function parseUnmaskFromPath(pathname: string): string | null {
+  const lastSlash = pathname.lastIndexOf('/')
+  const lastSegment = pathname.slice(lastSlash + 1)
+  const separatorIndex = lastSegment.indexOf(UNMASK_SEPARATOR)
+
+  if (separatorIndex === -1) return null
+
+  const encoded = lastSegment.slice(separatorIndex + UNMASK_SEPARATOR.length)
+  if (!encoded) return null
+
+  try {
+    return decodeUnmask(encoded)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Finds a matching route mask for a given pathname.
+ * Returns the mask result to apply, or undefined if no match.
+ */
+export function findMatchingMask(
+  pathname: string,
+  routeMasks: RouteMask[]
+):
+  | {
+      maskedPath: string
+      unmaskOnReload: boolean
+      useSearchParam: boolean
+      actualPath: string
+    }
+  | undefined {
+  for (const mask of routeMasks) {
+    const matchedParams = matchRouteMask(pathname, mask)
+    if (matchedParams) {
+      const maskedPath = buildMaskedPath(mask, matchedParams)
+      const useSearchParam = mask.useSearchParam ?? false
+      return {
+        // If useSearchParam is true, append base64-encoded actual path as pathname postfix
+        // e.g. /photos/3__L3Bob3Rvcy8zL21vZGFs
+        maskedPath: useSearchParam
+          ? `${maskedPath}${UNMASK_SEPARATOR}${encodeUnmask(pathname)}`
+          : maskedPath,
+        unmaskOnReload: mask.unmaskOnReload ?? false,
+        useSearchParam,
+        actualPath: pathname,
+      }
+    }
+  }
+  return undefined
+}

package/src/router/router.ts

@@ -51,11 +51,43 @@ import { preloadRouteModules } from './useViteRoutes'
 import { getNavigateAction } from './utils/getNavigateAction'
 import { setClientMatches } from '../useMatches'
 import type { RouteMatch } from '../useMatches'
+import { type RouteMask, findMatchingMask } from './routeMask'
 
 // Module-scoped variables
 export let routeNode: RouteNode | null = null
 export let rootComponent: ComponentType
 
+// Route masks for automatic URL masking
+let routeMasks: RouteMask[] = []
+
+/**
+ * Set route masks for automatic URL masking during navigation.
+ * Route masks transform URLs displayed in the browser without changing the actual route.
+ *
+ * @example
+ * ```tsx
+ * import { setRouteMasks, createRouteMask } from 'one'
+ *
+ * setRouteMasks([
+ *   createRouteMask({
+ *     from: '/photos/[id]/modal',
+ *     to: '/photos/[id]',
+ *     unmaskOnReload: true,
+ *   }),
+ * ])
+ * ```
+ */
+export function setRouteMasks(masks: RouteMask[]) {
+  routeMasks = masks
+}
+
+/**
+ * Get the current route masks.
+ */
+export function getRouteMasks(): RouteMask[] {
+  return routeMasks
+}
+
 // Global registry for protected routes
 // Key: contextKey (e.g., '/protected-test'), Value: Set of protected route names
 const protectedRouteRegistry = new Map<string, Set<string>>()
@@ -1002,8 +1034,28 @@ export async function linkTo(
     hashes[rootState.key] = href.slice(hash)
   }
 
+  // Auto-apply route mask if no explicit mask provided and routeMasks are configured
+  let finalOptions = options ?? null
+  if (!finalOptions?.mask && routeMasks.length > 0) {
+    // Extract pathname from href (remove search params and hash)
+    const pathname = extractPathnameFromHref(href)
+    const maskResult = findMatchingMask(pathname, routeMasks)
+    if (maskResult) {
+      finalOptions = {
+        ...finalOptions,
+        mask: {
+          href: maskResult.maskedPath,
+          unmaskOnReload: maskResult.unmaskOnReload,
+        },
+      }
+      if (process.env.ONE_DEBUG_ROUTER) {
+        console.info(`[one] 🎭 Auto-masked ${pathname} → ${maskResult.maskedPath}`)
+      }
+    }
+  }
+
   // a bit hacky until can figure out a reliable way to tie it to the state
-  nextOptions = options ?? null
+  nextOptions = finalOptions
 
   startTransition(() => {
     const action = getNavigateAction(state, rootState, event)

package/src/router/useScreens.tsx

@@ -7,7 +7,7 @@ import type {
   RouteProp,
   ScreenListeners,
 } from '@react-navigation/native'
-import React, { memo, Suspense, useEffect, useId, useState } from 'react'
+import React, { memo, Suspense, useEffect, useState } from 'react'
 import { SafeAreaView, ScrollView, Text, TouchableOpacity, View } from 'react-native'
 import { ServerContextScript } from '../server/ServerContextScript'
 import { getPageExport } from '../utils/getPageExport'
@@ -27,6 +27,46 @@ import { sortRoutesWithInitial } from './sortRoutes'
 
 // `@react-navigation/core` does not expose the Screen or Group components directly, so we have to
 // do this hack.
+
+/**
+ * Recursively check if React children contain a <meta charSet /> element.
+ * This is used to warn developers if they're missing the charset meta tag
+ * which can cause React hydration issues due to encoding mismatch.
+ */
+function hasMetaCharset(children: React.ReactNode): boolean {
+  if (process.env.NODE_ENV === 'development') {
+    if (!children) return false
+
+    const checkElement = (child: React.ReactNode): boolean => {
+      if (!React.isValidElement(child)) return false
+
+      // check if this is a <meta charSet /> or <meta charset />
+      if (child.type === 'meta') {
+        const props = child.props as Record<string, unknown>
+        if ('charSet' in props || 'charset' in props) {
+          return true
+        }
+      }
+
+      // recurse into children
+      const childProps = child.props as { children?: React.ReactNode }
+      if (childProps.children) {
+        return hasMetaCharset(childProps.children)
+      }
+
+      return false
+    }
+
+    if (Array.isArray(children)) {
+      return children.some(checkElement)
+    }
+
+    return checkElement(children)
+  }
+
+  return true
+}
+
 export const { Screen, Group } = createNavigatorFactory({} as any)()
 
 // Cache inline CSS elements at module load (before React hydrates).
@@ -89,10 +129,22 @@ function RootLayoutRenderer({
     return finalChildren
   }
 
+  if (process.env.NODE_ENV === 'development') {
+    // check if <meta charSet /> is present in head children
+    // if not, warn that it must be set in root _layout.tsx or else
+    // React will have hydration issues as it switches encoding
+    if (!hasMetaCharset(headChildren)) {
+      console.warn(
+        `[one] Missing <meta charSet="utf-8" /> in your root _layout.tsx <head>. ` +
+          `This can cause React hydration issues due to encoding mismatch. ` +
+          `Add it as the first element in your <head> tag.`
+      )
+    }
+  }
+
   finalChildren = (
     <>
       <head key="head" {...headProps}>
-        <meta charSet="utf-8" />
         <DevHead />
         <script
           dangerouslySetInnerHTML={{

package/src/ui/TabSlot.tsx

@@ -55,7 +55,8 @@ export function useTabSlot({
   style,
   renderFn = defaultTabsSlotRender,
 }: TabSlotProps = {}) {
-  const { state, descriptors } = useNavigatorContext()
+  const { state, descriptorsRef } = useNavigatorContext()
+  const descriptors = descriptorsRef.current
   const focusedRouteKey = state.routes[state.index].key
   const [loaded, setLoaded] = useState({ [focusedRouteKey]: true })
 

package/src/ui/Tabs.tsx

@@ -18,6 +18,7 @@ import {
   type ReactNode,
   use,
   useMemo,
+  useRef,
 } from 'react'
 import { StyleSheet, View, type ViewProps } from 'react-native'
 import { useRouteInfo } from '../hooks'
@@ -42,7 +43,7 @@ type NavigatorContextValue = {
   contextKey: string
   state: ReturnType<typeof useNavigationBuilder>['state']
   navigation: ReturnType<typeof useNavigationBuilder>['navigation']
-  descriptors: ReturnType<typeof useNavigationBuilder>['descriptors']
+  descriptorsRef: React.MutableRefObject<ReturnType<typeof useNavigationBuilder>['descriptors']>
   router: RouterFactory<any, any, any>
 }
 
@@ -208,14 +209,20 @@ export function useTabsWithTriggers(
     NavigationContent: RNNavigationContent,
   } = navigatorContext
 
-  const navigatorContextValue = useMemo<NavigatorContextValue>(
+  // HYDRATION FIX: Use ref for descriptors to avoid context invalidation during hydration.
+  const descriptorsRef = useRef(descriptors)
+  descriptorsRef.current = descriptors
+
+  const navigatorContextValue = useMemo(
     () => ({
-      ...(navigatorContext as unknown as ReturnType<typeof useNavigationBuilder>),
+      state,
+      navigation,
       contextKey,
       router: ExpoTabRouter,
+      descriptorsRef,
     }),
-    [navigatorContext, contextKey, ExpoTabRouter]
-  )
+    [state, navigation, contextKey, ExpoTabRouter]
+  ) as unknown as NavigatorContextValue
 
   const NavigationContent = useComponent((children: React.ReactNode) => (
     <TabTriggerMapContext.Provider value={triggerMap}>

package/src/views/Navigator.tsx

@@ -24,7 +24,7 @@ export const NavigatorContext = React.createContext<{
   contextKey: string
   state: NavigatorTypes['state']
   navigation: NavigatorTypes['navigation']
-  descriptors: NavigatorTypes['descriptors']
+  descriptorsRef: React.MutableRefObject<NavigatorTypes['descriptors']>
   router: RouterFactory<any, any, any>
 } | null>(null)
 
@@ -122,15 +122,22 @@ function QualifiedNavigator({
     }
   )
 
+  // HYDRATION FIX: Use ref for descriptors to avoid context invalidation during hydration.
+  // The descriptors object changes by reference on each render from useNavigationBuilder,
+  // but the actual content is the same. By using a ref, we prevent unnecessary re-renders
+  // that cause React to abandon hydration and remount the component tree.
+  const descriptorsRef = React.useRef(descriptors)
+  descriptorsRef.current = descriptors
+
   const value = React.useMemo(() => {
     return {
       contextKey,
       state,
       navigation,
-      descriptors,
+      descriptorsRef,
       router,
     }
-  }, [contextKey, state, navigation, descriptors, router])
+  }, [contextKey, state, navigation, router])
 
   return (
     <NavigatorContext.Provider value={value}>
@@ -149,7 +156,7 @@ export function useNavigatorContext() {
 
 export function useSlot() {
   const context = useNavigatorContext()
-  const { state, descriptors } = context
+  const { state, descriptorsRef } = context
 
   const current = state.routes.find((route, i) => {
     return state.index === i
@@ -159,15 +166,13 @@ export function useSlot() {
     return null
   }
 
-  const renderedElement = descriptors[current.key]?.render() ?? null
+  const renderedElement = descriptorsRef.current[current.key]?.render() ?? null
 
   // Use static key to prevent layout remounts when route keys change during navigation.
   // Safe because Slot only renders one screen at a time.
+  // Use cloneElement to properly clone the React element with a new key.
   if (renderedElement !== null) {
-    return {
-      ...renderedElement,
-      key: SLOT_STATIC_KEY,
-    }
+    return React.cloneElement(renderedElement, { key: SLOT_STATIC_KEY })
   }
 
   return renderedElement