zelune 1.5.4 → 1.5.5

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to the **Zelune — React Native Visual Canvas & MCP** project are documented in this file.
 
+## [1.5.5] - 2026-10-23
+
+### Added
+- **Zod, React Hook Form & Sizing Utility Shims (`src/runtime/MockNavigationContext.tsx`, `plugins/viteReactNativeFallbackPlugin.ts`)**: Added `createSafeChainableProxy()` / `SAFE_CHAINABLE_PROXY` (wrapping a callable function target in a recursive `Proxy` for unlimited method/property chains), full Zod schema shims (`z`, `string`, `number`, `boolean`, `object`, `array`, `union`, `literal`, `record`, `tuple`, `any`, `unknown`, `optional`, `nullable`, `coerce`, `zodResolver`, `yupResolver`), React Hook Form shims (`useForm`, `useFormContext`, `FormProvider`, `useWatch`, `useFieldArray`, `Controller` supporting `render={({ field, fieldState, formState }) => ...}`), and React Native responsive sizing/classname helpers (`scale`, `verticalScale`, `moderateScale`, `RFValue`, `RFPercentage`, `wp`, `hp`, `clsx`, `cn`, `twMerge`).
+- **Universal Unmounted React Context Fallback (`src/runtime/MockNavigationContext.tsx`, `src/main.tsx`)**: Wrapped `React.createContext` and `React.useContext` (after `react-native-web` initializes its internal contexts) with `SAFE_CONTEXT_FALLBACK` (pre-populated with preview `user`, `profile`, `session`, `isAuthenticated: true`, `isLoading: false`, `colors`, `items: []`, `signIn`, `signOut`, `logout`, `refresh`, etc.) so screens rendered outside their root `app/_layout.tsx` providers never throw `useAuth must be used within an AuthProvider` (or `useTheme` / `useCart` / `useNotifications` equivalents).
+
+### Fixed
+- **Eliminated Canvas Panning Vibration / Jitter (`src/canvas/CanvasApp.tsx`, `src/canvas/ScreenArtboard.tsx`, `src/canvas/FlowArrowsLayer.tsx`)**:
+  - Updated `handleCanvasWheel` and `handleCanvasPointerDown` in `CanvasApp.tsx` to mutate `worldContainerRef.current.style.transform` (`translate3d(...) scale(...)`) directly on the DOM node with device-pixel rounding (`snapToDevicePixel`) and debounce `setPan` state synchronization to 120ms after movement stops, eliminating 120Hz React re-renders of all artboards while panning.
+  - Wrapped `ScreenArtboard` and `FlowArrowsLayer` in `React.memo`, scoped `selectedElement` and `inspectedElement` props to only the active screen, and suppressed `handlePointerMoveCapture` (`computeRelativeBox` / `setHoverBox`) while the canvas is moving or pointer buttons are pressed.
+  - Stabilized `useFocusEffect`, `useSegments`, `useQuery`, `useInfiniteQuery`, `useMutation`, and `useQueryClient` in `MockNavigationContext.tsx` so screens with inline `useFocusEffect` or `useEffect` dependencies do not trigger continuous re-render loops.
+- **Light-Themed Screen Root Background & Image Overflow (`src/canvas/ScreenArtboard.tsx`)**: Set `backgroundColor: '#FFFFFF'`, `color: '#0F172A'`, `overflowY: 'auto'`, `overflowX: 'hidden'`, `minWidth: 0`, and `minHeight: 0` on the inner `<ScreenComponent />` mount container so screens that rely on React Native's default white root window background render with proper contrast and horizontally overflowing images are clipped to the 393px device frame.
+
 ## [1.5.4] - 2026-10-23
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zelune",
-  "version": "1.5.4",
+  "version": "1.5.5",
   "private": false,
   "license": "MIT",
   "type": "module",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "zelune",
   "displayName": "Zelune — React Native Visual Canvas",
-  "version": "1.5.4",
+  "version": "1.5.5",
   "description": "Zelune MCP & Figma-style multi-screen React Native visual canvas with live surgical AST patching and navigation flow visualization for Google Antigravity.",
   "logo": "assets/logo.svg",
   "suggestedPrompts": [

package/plugins/viteReactNativeFallbackPlugin.ts

@@ -484,53 +484,18 @@ export function viteReactNativeFallbackPlugin(
         `import { View } from 'react-native';`,
         `export * from ${JSON.stringify(normalizedShimPath)};`,
         `import * as KnownShims from ${JSON.stringify(normalizedShimPath)};`,
-        `import DefaultShim from ${JSON.stringify(normalizedShimPath)};`,
-        `function createSafeProxy() {`,
-        `  const fnTarget = function(...args) {`,
-        `    if (args.length === 1 && (typeof args[0] === 'number' || typeof args[0] === 'string')) {`,
-        `      return args[0];`,
-        `    }`,
-        `    return proxy;`,
-        `  };`,
-        `  const arrTarget = [];`,
-        `  const proxy = new Proxy(arrTarget, {`,
-        `    get(target, prop) {`,
-        `      if (prop === 'length') return 0;`,
-        `      if (prop === Symbol.iterator) {`,
-        `        return function* () {`,
-        `          yield proxy;`,
-        `          yield fnTarget;`,
-        `        };`,
-        `      }`,
-        `      if (prop === Symbol.toPrimitive) {`,
-        `        return (hint) => (hint === 'number' ? 0 : '');`,
-        `      }`,
-        `      if (prop === 'valueOf') return () => 0;`,
-        `      if (prop === 'toString') return () => '';`,
-        `      if (prop === 'then') {`,
-        `        return (onFulfilled, onRejected) => Promise.resolve({ data: null, error: null }).then(onFulfilled, onRejected);`,
-        `      }`,
-        `      if (prop === 'catch') return () => Promise.resolve({ data: null, error: null });`,
-        `      if (prop === 'finally') return (cb) => Promise.resolve({ data: null, error: null }).finally(cb);`,
-        `      if (prop === 'isLoading' || prop === 'loading' || prop === 'isPending' || prop === 'isError' || prop === 'disabled') return false;`,
-        `      if (prop === 'isReady' || prop === 'granted' || prop === 'isSuccess' || prop === ' isAuthenticated') return true;`,
-        `      if (prop === 'error' || prop === 'user' || prop === 'session') return null;`,
-        `      if (prop === 'status') return 'granted';`,
-        `      if (prop === 'data' || prop === 'items' || prop === 'results' || prop === 'list') return [];`,
-        `      if (prop === 'ref') return { current: null };`,
-        `      if (prop === 'value') return 0;`,
-        `      if (prop === 'map' || prop === 'filter' || prop === 'slice' || prop === 'flatMap') return () => [];`,
-        `      if (prop === 'forEach') return () => undefined;`,
-        `      if (prop === 'reduce') return (_fn, init) => init;`,
-        `      if (prop in target) return Reflect.get(target, prop);`,
-        `      return fnTarget;`,
-        `    },`,
-        `  });`,
-        `  return proxy;`,
-        `}`,
+        `import DefaultShim, { SAFE_CHAINABLE_PROXY } from ${JSON.stringify(normalizedShimPath)};`,
         `function createUniversalComponentStub(displayName) {`,
         `  const Comp = React.forwardRef(function UniversalNativeStub(props, ref) {`,
-        `    return React.createElement(View, { style: props?.style, ref }, props?.children);`,
+        `    if (typeof props?.render === 'function') {`,
+        `      return props.render({`,
+        `        field: { name: props?.name ?? '', value: props?.defaultValue ?? '', onChange: () => undefined, onBlur: () => undefined, ref: () => undefined },`,
+        `        fieldState: { invalid: false, isTouched: false, isDirty: false, error: undefined },`,
+        `        formState: { errors: {}, isSubmitting: false, isValid: true },`,
+        `      });`,
+        `    }`,
+        `    const content = typeof props?.children === 'function' ? props.children(SAFE_CHAINABLE_PROXY) : props?.children;`,
+        `    return React.createElement(View, { style: props?.style, ref }, content);`,
         `  });`,
         `  Comp.displayName = displayName;`,
         `  return new Proxy(Comp, {`,
@@ -539,21 +504,16 @@ export function viteReactNativeFallbackPlugin(
         `      if (typeof prop === 'string' && /^[A-Z]/.test(prop)) {`,
         `        return createUniversalComponentStub(displayName + '.' + prop);`,
         `      }`,
-        `      return () => createSafeProxy();`,
+        `      return SAFE_CHAINABLE_PROXY;`,
         `    },`,
         `  });`,
         `}`,
         `function resolveStubExport(name) {`,
         `  if (name in KnownShims) return KnownShims[name];`,
         `  if (DefaultShim && name in DefaultShim) return DefaultShim[name];`,
-        `  if (/^use[A-Z]/.test(name)) return () => createSafeProxy();`,
+        `  if (/^use[A-Z]/.test(name)) return () => SAFE_CHAINABLE_PROXY;`,
         `  if (/^[A-Z]/.test(name)) return createUniversalComponentStub(name);`,
-        `  return (...args) => {`,
-        `    if (args.length === 1 && (typeof args[0] === 'number' || typeof args[0] === 'string')) {`,
-        `      return args[0];`,
-        `    }`,
-        `    return createSafeProxy();`,
-        `  };`,
+        `  return SAFE_CHAINABLE_PROXY;`,
         `}`,
         `export default DefaultShim;`,
       ];

package/src/canvas/CanvasApp.tsx

@@ -45,6 +45,11 @@ function clampZoom(z: number): number {
   return Number(Math.min(Math.max(z, MIN_ZOOM), MAX_ZOOM).toFixed(3));
 }
 
+function snapToDevicePixel(v: number): number {
+  const dpr = typeof window !== 'undefined' ? window.devicePixelRatio || 1 : 1;
+  return Math.round(v * dpr) / dpr;
+}
+
 function buildDefaultLayout(screens: ScreenMetadata[]): ArtboardLayoutMap {
   const map: ArtboardLayoutMap = {};
   screens.forEach((screen, idx) => {
@@ -128,7 +133,9 @@ export const CanvasApp: React.FC = () => {
   }>({ undoAvailable: 0, redoAvailable: 0 });
 
   const canvasViewportRef = useRef<HTMLDivElement | null>(null);
+  const worldContainerRef = useRef<HTMLDivElement | null>(null);
   const cameraTimerRef = useRef<number | null>(null);
+  const panSyncTimerRef = useRef<number | null>(null);
 
   // Refs for synchronous access inside non-passive native wheel/gesture listeners
   const zoomRef = useRef<number>(zoom);
@@ -140,6 +147,39 @@ export const CanvasApp: React.FC = () => {
     panRef.current = pan;
   }, [pan]);
 
+  const applyDirectPanTransform = useCallback(
+    (rawX: number, rawY: number, commitImmediately = false) => {
+      const nextPan = {
+        x: snapToDevicePixel(rawX),
+        y: snapToDevicePixel(rawY),
+      };
+      panRef.current = nextPan;
+
+      const worldEl = worldContainerRef.current;
+      if (worldEl) {
+        worldEl.style.transition = 'none';
+        worldEl.style.transform = `translate3d(${nextPan.x}px, ${nextPan.y}px, 0) scale(${zoomRef.current})`;
+      }
+
+      if (panSyncTimerRef.current) {
+        window.clearTimeout(panSyncTimerRef.current);
+        panSyncTimerRef.current = null;
+      }
+
+      if (commitImmediately) {
+        setIsCameraAnimating(false);
+        setPan(nextPan);
+      } else {
+        panSyncTimerRef.current = window.setTimeout(() => {
+          panSyncTimerRef.current = null;
+          setIsCameraAnimating(false);
+          setPan(panRef.current);
+        }, 120);
+      }
+    },
+    []
+  );
+
   const triggerCameraTransition = useCallback(() => {
     if (cameraTimerRef.current) {
       window.clearTimeout(cameraTimerRef.current);
@@ -462,13 +502,17 @@ export const CanvasApp: React.FC = () => {
       const worldY = (cursorY - prevPan.y) / prevZoom;
 
       const nextPan = {
-        x: cursorX - worldX * nextZoom,
-        y: cursorY - worldY * nextZoom,
+        x: snapToDevicePixel(cursorX - worldX * nextZoom),
+        y: snapToDevicePixel(cursorY - worldY * nextZoom),
       };
 
       setIsCameraAnimating(false);
       zoomRef.current = nextZoom;
       panRef.current = nextPan;
+      if (worldContainerRef.current) {
+        worldContainerRef.current.style.transition = 'none';
+        worldContainerRef.current.style.transform = `translate3d(${nextPan.x}px, ${nextPan.y}px, 0) scale(${nextZoom})`;
+      }
       setZoom(nextZoom);
       setPan(nextPan);
     };
@@ -483,13 +527,11 @@ export const CanvasApp: React.FC = () => {
         const zoomFactor = Math.exp(-e.deltaY * 0.0085);
         applyFocalZoom(zoomRef.current * zoomFactor, e.clientX, e.clientY);
       } else {
-        setIsCameraAnimating(false);
-        const nextPan = {
-          x: panRef.current.x - e.deltaX,
-          y: panRef.current.y - e.deltaY,
-        };
-        panRef.current = nextPan;
-        setPan(nextPan);
+        applyDirectPanTransform(
+          panRef.current.x - e.deltaX,
+          panRef.current.y - e.deltaY,
+          false
+        );
       }
     };
 
@@ -537,7 +579,7 @@ export const CanvasApp: React.FC = () => {
       document.removeEventListener('gesturechange', handleGestureChange);
       document.removeEventListener('gestureend', handleGestureEnd);
     };
-  }, []);
+  }, [applyDirectPanTransform]);
 
   // Center viewport on a specific screen artboard using Emil Kowalski ease-out-expo camera physics
   const focusOnScreen = useCallback(
@@ -630,7 +672,14 @@ export const CanvasApp: React.FC = () => {
     [focusOnScreen]
   );
 
-  // Canvas background pointer pan (0ms direct manipulation override)
+  const handleSelectFlow = useCallback(
+    (edge: NavigationEdge) => {
+      focusOnScreen(edge.toScreen);
+    },
+    [focusOnScreen]
+  );
+
+  // Canvas background pointer pan (0ms direct DOM manipulation override)
   const handleCanvasPointerDown = (e: React.PointerEvent<HTMLDivElement>) => {
     if (e.button !== 0 && e.button !== 1) return;
     setIsCameraAnimating(false);
@@ -638,20 +687,20 @@ export const CanvasApp: React.FC = () => {
 
     const startX = e.clientX;
     const startY = e.clientY;
-    const startPanX = pan.x;
-    const startPanY = pan.y;
+    const startPanX = panRef.current.x;
+    const startPanY = panRef.current.y;
 
     const handleMove = (moveEvent: PointerEvent) => {
-      const nextPan = {
-        x: startPanX + (moveEvent.clientX - startX),
-        y: startPanY + (moveEvent.clientY - startY),
-      };
-      panRef.current = nextPan;
-      setPan(nextPan);
+      applyDirectPanTransform(
+        startPanX + (moveEvent.clientX - startX),
+        startPanY + (moveEvent.clientY - startY),
+        false
+      );
     };
 
     const handleUp = () => {
       setIsPanning(false);
+      applyDirectPanTransform(panRef.current.x, panRef.current.y, true);
       window.removeEventListener('pointermove', handleMove);
       window.removeEventListener('pointerup', handleUp);
     };
@@ -1299,6 +1348,7 @@ export const CanvasApp: React.FC = () => {
 
           {/* World Transform Container: Emil Kowalski ease-out-expo on camera focus, 0ms on direct drag/pinch */}
           <div
+            ref={worldContainerRef}
             style={{
               position: 'absolute',
               top: 0,
@@ -1306,6 +1356,7 @@ export const CanvasApp: React.FC = () => {
               transform: `translate3d(${pan.x}px, ${pan.y}px, 0) scale(${zoom})`,
               transformOrigin: '0 0',
               willChange: 'transform',
+              backfaceVisibility: 'hidden',
               transition: isCameraAnimating
                 ? 'transform var(--duration-camera) var(--ease-out-expo)'
                 : 'none',
@@ -1317,7 +1368,7 @@ export const CanvasApp: React.FC = () => {
                 layout={layout}
                 activeScreenId={activeScreenId}
                 highlightedScreenId={highlightedScreenId}
-                onSelectFlow={(edge: NavigationEdge) => focusOnScreen(edge.toScreen)}
+                onSelectFlow={handleSelectFlow}
               />
             )}
 
@@ -1329,6 +1380,7 @@ export const CanvasApp: React.FC = () => {
                 height: DEFAULT_HEIGHT,
               };
               const ScreenComponent = SCREEN_COMPONENTS[screen.id];
+              const isSelectedScreen = selectedElement?.screenId === screen.id;
 
               return (
                 <ScreenArtboard
@@ -1340,8 +1392,9 @@ export const CanvasApp: React.FC = () => {
                   mode={mode}
                   isActiveScreen={activeScreenId === screen.id}
                   isHighlightedScreen={highlightedScreenId === screen.id}
-                  selectedElement={selectedElement}
-                  inspectedElement={inspectedData}
+                  isCanvasMoving={isPanning}
+                  selectedElement={isSelectedScreen ? selectedElement : null}
+                  inspectedElement={isSelectedScreen ? inspectedData : null}
                   onSelectElement={handleSelectElement}
                   onSelectScreen={setActiveScreenId}
                   onFocusScreen={focusOnScreen}

package/src/canvas/FlowArrowsLayer.tsx

@@ -11,7 +11,7 @@ interface FlowArrowsLayerProps {
 
 const ARTBOARD_HEADER_OFFSET = 38;
 
-export const FlowArrowsLayer: React.FC<FlowArrowsLayerProps> = ({
+export const FlowArrowsLayer: React.FC<FlowArrowsLayerProps> = React.memo(({
   screens,
   layout,
   activeScreenId,
@@ -194,4 +194,4 @@ export const FlowArrowsLayer: React.FC<FlowArrowsLayerProps> = ({
       })}
     </svg>
   );
-};
+});

package/src/canvas/ScreenArtboard.tsx

@@ -29,6 +29,7 @@ interface ScreenArtboardProps {
   mode: CanvasMode;
   isActiveScreen: boolean;
   isHighlightedScreen: boolean;
+  isCanvasMoving?: boolean;
   selectedElement: SelectedElementRef | null;
   inspectedElement: InspectedElement | null;
   onSelectElement: (ref: SelectedElementRef) => void;
@@ -83,7 +84,7 @@ function escapeAstPathSelector(astPath: string): string {
     : astPath.replace(/["\\]/g, '\\$&');
 }
 
-export const ScreenArtboard: React.FC<ScreenArtboardProps> = ({
+export const ScreenArtboard: React.FC<ScreenArtboardProps> = React.memo(({
   screen,
   ScreenComponent,
   position,
@@ -91,6 +92,7 @@ export const ScreenArtboard: React.FC<ScreenArtboardProps> = ({
   mode,
   isActiveScreen,
   isHighlightedScreen,
+  isCanvasMoving = false,
   selectedElement,
   inspectedElement,
   onSelectElement,
@@ -732,8 +734,14 @@ export const ScreenArtboard: React.FC<ScreenArtboardProps> = ({
   };
 
   // Inspect Mode pointer handlers
+  useEffect(() => {
+    if (isCanvasMoving) {
+      setHoverBox(null);
+    }
+  }, [isCanvasMoving]);
+
   const handlePointerMoveCapture = (e: React.PointerEvent<HTMLDivElement>) => {
-    if (mode !== 'inspect' || activeGizmoAction) return;
+    if (mode !== 'inspect' || activeGizmoAction || isCanvasMoving || e.buttons !== 0) return;
     const targetEl = findNearestAgyElement(e.target, viewportRef.current);
     if (!targetEl) {
       setHoverBox(null);
@@ -992,6 +1000,12 @@ export const ScreenArtboard: React.FC<ScreenArtboardProps> = ({
                   flexDirection: 'column',
                   height: '100%',
                   width: '100%',
+                  minHeight: 0,
+                  minWidth: 0,
+                  backgroundColor: '#FFFFFF',
+                  color: '#0F172A',
+                  overflowY: 'auto',
+                  overflowX: 'hidden',
                 }}
               >
                 <ScreenComponent />
@@ -1474,4 +1488,4 @@ export const ScreenArtboard: React.FC<ScreenArtboardProps> = ({
       </div>
     </div>
   );
-};
+});

package/src/main.tsx

@@ -1,5 +1,6 @@
 import React from 'react';
 import ReactDOM from 'react-dom/client';
+import './runtime/MockNavigationContext';
 import { CanvasApp } from './canvas/CanvasApp';
 import './styles.css';
 

package/src/runtime/MockNavigationContext.tsx

@@ -128,13 +128,17 @@ export function useRoute(): { key: string; name: string; params: Record<string,
 }
 
 export function useFocusEffect(effect: () => void | (() => void)): void {
+  const ctx = useContext(MockNavigationContext);
+  const effectRef = useRef(effect);
+  effectRef.current = effect;
   useEffect(() => {
     try {
-      return effect();
+      const cleanup = effectRef.current();
+      return typeof cleanup === 'function' ? cleanup : undefined;
     } catch {
       return undefined;
     }
-  }, [effect]);
+  }, [ctx.currentRoute]);
 }
 
 export function useIsFocused(): boolean {
@@ -242,7 +246,7 @@ export function usePathname(): string {
 
 export function useSegments(): string[] {
   const ctx = useContext(MockNavigationContext);
-  return [ctx.currentRoute.toLowerCase()];
+  return useMemo(() => [ctx.currentRoute.toLowerCase()], [ctx.currentRoute]);
 }
 
 export function useRootNavigationState() {
@@ -973,53 +977,477 @@ export const QueryClientProvider: React.FC<{ client?: unknown; children?: React.
   children,
 }) => <>{children}</>;
 
+const singletonQueryClient = new QueryClient();
+
 export function useQueryClient() {
-  return new QueryClient();
+  return singletonQueryClient;
 }
 
+const STABLE_EMPTY_ARRAY: unknown[] = [];
+
+const STABLE_QUERY_RESULT = {
+  data: undefined,
+  error: null,
+  isLoading: false,
+  isPending: false,
+  isFetching: false,
+  isError: false,
+  isSuccess: true,
+  status: 'success',
+  refetch: async () => ({ data: undefined, error: null }),
+};
+
 export function useQuery() {
-  return {
-    data: undefined,
-    error: null,
-    isLoading: false,
-    isPending: false,
-    isFetching: false,
-    isError: false,
-    isSuccess: true,
-    status: 'success',
-    refetch: async () => ({ data: undefined, error: null }),
-  };
-}
+  return STABLE_QUERY_RESULT;
+}
+
+const STABLE_INFINITE_QUERY_RESULT = {
+  data: { pages: STABLE_EMPTY_ARRAY, pageParams: STABLE_EMPTY_ARRAY },
+  error: null,
+  isLoading: false,
+  isPending: false,
+  isFetching: false,
+  isFetchingNextPage: false,
+  hasNextPage: false,
+  fetchNextPage: async () => ({}),
+  refetch: async () => ({}),
+};
 
 export function useInfiniteQuery() {
-  return {
-    data: { pages: [], pageParams: [] },
-    error: null,
-    isLoading: false,
-    isPending: false,
-    isFetching: false,
-    isFetchingNextPage: false,
-    hasNextPage: false,
-    fetchNextPage: async () => ({}),
-    refetch: async () => ({}),
-  };
+  return STABLE_INFINITE_QUERY_RESULT;
 }
 
+const STABLE_MUTATION_RESULT = {
+  mutate: () => undefined,
+  mutateAsync: async () => ({}),
+  reset: () => undefined,
+  data: undefined,
+  error: null,
+  isLoading: false,
+  isPending: false,
+  isError: false,
+  isSuccess: false,
+  status: 'idle',
+};
+
 export function useMutation() {
+  return STABLE_MUTATION_RESULT;
+}
+
+// ============================================================================
+// 11. Universal Chainable Proxy, Zod, React Hook Form & Context Fallbacks
+// ============================================================================
+export function createSafeChainableProxy(): unknown {
+  const fnTarget = function (..._args: unknown[]) {
+    return proxy;
+  };
+  const proxy: unknown = new Proxy(fnTarget, {
+    get(_target, prop) {
+      if (prop === Symbol.toPrimitive) {
+        return (hint: string) => (hint === 'number' ? 0 : '');
+      }
+      if (prop === 'valueOf') return () => 0;
+      if (prop === 'toString') return () => '';
+      if (prop === Symbol.iterator) {
+        return function* () {
+          yield proxy;
+          yield proxy;
+        };
+      }
+      if (prop === 'then') {
+        return (onFulfilled?: (v: unknown) => unknown, onRejected?: (e: unknown) => unknown) =>
+          Promise.resolve({ data: null, error: null }).then(onFulfilled, onRejected);
+      }
+      if (prop === 'catch') return () => Promise.resolve({ data: null, error: null });
+      if (prop === 'finally')
+        return (cb?: () => void) => Promise.resolve({ data: null, error: null }).finally(cb);
+      if (prop === 'safeParse' || prop === 'spa' || prop === 'safeParseAsync') {
+        return (val?: unknown) => ({ success: true, data: val ?? {}, error: null });
+      }
+      if (prop === 'parse' || prop === 'parseAsync') {
+        return (val?: unknown) => val ?? {};
+      }
+      if (
+        prop === 'isLoading' ||
+        prop === 'loading' ||
+        prop === 'isPending' ||
+        prop === 'isError' ||
+        prop === 'disabled' ||
+        prop === 'isSubmitting'
+      ) {
+        return false;
+      }
+      if (
+        prop === 'isReady' ||
+        prop === 'granted' ||
+        prop === 'isSuccess' ||
+        prop === 'isAuthenticated' ||
+        prop === 'isValid'
+      ) {
+        return true;
+      }
+      if (prop === 'error' || prop === 'errors') return null;
+      if (prop === 'status') return 'granted';
+      if (prop === 'data' || prop === 'items' || prop === 'results' || prop === 'list') {
+        return STABLE_EMPTY_ARRAY;
+      }
+      if (prop === 'length' || prop === 'size' || prop === 'count' || prop === 'value') return 0;
+      if (prop === 'ref') return { current: null };
+      if (prop === 'map' || prop === 'filter' || prop === 'slice' || prop === 'flatMap') {
+        return () => STABLE_EMPTY_ARRAY;
+      }
+      if (prop === 'forEach') return () => undefined;
+      if (prop === 'reduce') return (_fn: unknown, init: unknown) => init;
+      if (prop === 'shape' || prop === '_def') return {};
+      return proxy;
+    },
+  });
+  return proxy;
+}
+
+export const SAFE_CHAINABLE_PROXY = createSafeChainableProxy();
+
+// Zod Shims (import { z } from 'zod' or import * as z from 'zod')
+export const z = SAFE_CHAINABLE_PROXY as Record<string, unknown>;
+export const string = () => SAFE_CHAINABLE_PROXY;
+export const number = () => SAFE_CHAINABLE_PROXY;
+export const boolean = () => SAFE_CHAINABLE_PROXY;
+export const object = () => SAFE_CHAINABLE_PROXY;
+export const array = () => SAFE_CHAINABLE_PROXY;
+export const union = () => SAFE_CHAINABLE_PROXY;
+export const literal = () => SAFE_CHAINABLE_PROXY;
+export const record = () => SAFE_CHAINABLE_PROXY;
+export const tuple = () => SAFE_CHAINABLE_PROXY;
+export const any = () => SAFE_CHAINABLE_PROXY;
+export const unknown = () => SAFE_CHAINABLE_PROXY;
+export const optional = () => SAFE_CHAINABLE_PROXY;
+export const nullable = () => SAFE_CHAINABLE_PROXY;
+export const coerce = SAFE_CHAINABLE_PROXY;
+export const zodResolver = () => async (values: unknown) => ({
+  values: values ?? {},
+  errors: {},
+});
+export const yupResolver = zodResolver;
+
+// Common React Native Sizing & Classname Utility Shims
+export const scale = (size: number) => size;
+export const verticalScale = (size: number) => size;
+export const moderateScale = (size: number) => size;
+export const moderateVerticalScale = (size: number) => size;
+export const s = scale;
+export const vs = verticalScale;
+export const ms = moderateScale;
+export const mvs = moderateVerticalScale;
+export const RFValue = (size: number) => size;
+export const RFPercentage = (pct: number) => Math.round(pct * 8);
+export const widthPercentageToDP = (pct: number | string) =>
+  typeof pct === 'number' ? Math.round((393 * pct) / 100) : 100;
+export const heightPercentageToDP = (pct: number | string) =>
+  typeof pct === 'number' ? Math.round((852 * pct) / 100) : 100;
+export const wp = widthPercentageToDP;
+export const hp = heightPercentageToDP;
+export const clsx = (...args: unknown[]) =>
+  args.filter((a): a is string => typeof a === 'string' && a.length > 0).join(' ');
+export const cn = clsx;
+export const twMerge = clsx;
+
+// React Hook Form Shims (react-hook-form)
+export function useForm(config?: { defaultValues?: Record<string, unknown> }) {
+  const defaults = config?.defaultValues ?? {};
   return {
-    mutate: () => undefined,
-    mutateAsync: async () => ({}),
+    control: {},
+    register: (name: string) => ({
+      name,
+      onChange: () => undefined,
+      onBlur: () => undefined,
+      ref: () => undefined,
+    }),
+    handleSubmit: (onValid?: (data: Record<string, unknown>) => unknown) => () =>
+      onValid?.(defaults),
+    watch: (name?: string) => (name ? defaults[name] ?? '' : defaults),
+    getValues: (name?: string) => (name ? defaults[name] : defaults),
+    setValue: () => undefined,
     reset: () => undefined,
-    data: undefined,
-    error: null,
-    isLoading: false,
-    isPending: false,
-    isError: false,
-    isSuccess: false,
-    status: 'idle',
+    clearErrors: () => undefined,
+    setError: () => undefined,
+    trigger: async () => true,
+    formState: {
+      errors: {},
+      isDirty: false,
+      isLoading: false,
+      isSubmitted: false,
+      isSubmitting: false,
+      isSubmitSuccessful: false,
+      isValid: true,
+      dirtyFields: {},
+      touchedFields: {},
+    },
   };
 }
 
+export const useFormContext = () => useForm();
+export const FormProvider: React.FC<{ children?: React.ReactNode }> = ({ children }) => (
+  <>{children}</>
+);
+export const useWatch = () => '';
+export const useFieldArray = () => ({
+  fields: STABLE_EMPTY_ARRAY,
+  append: () => undefined,
+  prepend: () => undefined,
+  remove: () => undefined,
+  insert: () => undefined,
+   move: () => undefined,
+  update: () => undefined,
+  replace: () => undefined,
+});
+
+export const Controller: React.FC<{
+  name?: string;
+  defaultValue?: unknown;
+  render?: (params: {
+    field: {
+      name: string;
+      value: unknown;
+      onChange: (...args: unknown[]) => void;
+      onBlur: () => void;
+      ref: () => void;
+    };
+    fieldState: { invalid: boolean; isTouched: boolean; isDirty: boolean; error: undefined };
+    formState: { errors: Record<string, unknown>; isSubmitting: boolean; isValid: boolean };
+  }) => React.ReactNode;
+  children?: React.ReactNode;
+}> = ({ name = '', defaultValue = '', render, children }) => {
+  if (typeof render === 'function') {
+    return (
+      <>
+        {render({
+          field: {
+            name,
+            value: defaultValue ?? '',
+            onChange: () => undefined,
+            onBlur: () => undefined,
+            ref: () => undefined,
+          },
+          fieldState: { invalid: false, isTouched: false, isDirty: false, error: undefined },
+          formState: { errors: {}, isSubmitting: false, isValid: true },
+        })}
+      </>
+    );
+  }
+  return <>{children}</>;
+};
+
+// Universal Unmounted Context Fallback (prevents "useAuth must be used within an AuthProvider")
+const previewUserBase: Record<string, unknown> = {
+  id: 'usr_preview_01',
+  uid: 'usr_preview_01',
+  email: 'alex.morgan@example.com',
+  name: 'Alex Morgan',
+  fullName: 'Alex Morgan',
+  full_name: 'Alex Morgan',
+  firstName: 'Alex',
+  first_name: 'Alex',
+  lastName: 'Morgan',
+  last_name: 'Morgan',
+  displayName: 'Alex Morgan',
+  display_name: 'Alex Morgan',
+  username: 'alexmorgan',
+  phone: '+1 (555) 019-2834',
+  phoneNumber: '+1 (555) 019-2834',
+  phone_number: '+1 (555) 019-2834',
+  role: 'buyer',
+  accountType: 'buyer',
+  account_type: 'buyer',
+  location: 'San Francisco, CA',
+  city: 'San Francisco',
+  bio: 'Product designer & automotive enthusiast.',
+  avatar: '',
+  avatarUrl: '',
+  avatar_url: '',
+  photoURL: '',
+  profileImage: '',
+  profile_image: '',
+  isVerified: true,
+  is_verified: true,
+  verified: true,
+  createdAt: '2025-01-15T10:00:00Z',
+  created_at: '2025-01-15T10:00:00Z',
+  user_metadata: {
+    full_name: 'Alex Morgan',
+    name: 'Alex Morgan',
+    email: 'alex.morgan@example.com',
+    role: 'buyer',
+    avatar_url: '',
+  },
+  app_metadata: {
+    provider: 'email',
+    role: 'buyer',
+  },
+};
+
+const previewUserProxy = new Proxy(previewUserBase, {
+  get(target, prop) {
+    if (prop in target) return target[prop as keyof typeof target];
+    if (prop === Symbol.toPrimitive) return () => 'Alex Morgan';
+    if (typeof prop === 'string') return '';
+    return undefined;
+  },
+});
+
+const previewColorsBase: Record<string, string> = {
+  primary: '#2563EB',
+  primaryLight: '#DBEAFE',
+  secondary: '#64748B',
+  accent: '#4F46E5',
+  background: '#FFFFFF',
+  backgroundSecondary: '#F8FAFC',
+  surface: '#F8FAFC',
+  card: '#FFFFFF',
+  text: '#0F172A',
+  textPrimary: '#0F172A',
+  textSecondary: '#475569',
+  textMuted: '#94A3B8',
+  muted: '#94A3B8',
+  placeholder: '#94A3B8',
+  border: '#E2E8F0',
+  divider: '#E2E8F0',
+  error: '#EF4444',
+  danger: '#EF4444',
+  success: '#10B981',
+  warning: '#F59E0B',
+  info: '#3B82F6',
+  white: '#FFFFFF',
+  black: '#0F172A',
+  tint: '#2563EB',
+  icon: '#64748B',
+  tabIconDefault: '#94A3B8',
+  tabIconSelected: '#2563EB',
+  notification: '#EF4444',
+};
+
+const previewColorsProxy = new Proxy(previewColorsBase, {
+  get(target, prop) {
+    if (prop in target) return target[prop as keyof typeof target];
+    return '#64748B';
+  },
+});
+
+const safeContextFallbackBase: Record<string, unknown> = {
+  user: previewUserProxy,
+  currentUser: previewUserProxy,
+  profile: previewUserProxy,
+  session: {
+    access_token: 'preview-access-token',
+    refresh_token: 'preview-refresh-token',
+    user: previewUserProxy,
+  },
+  isAuthenticated: true,
+  isLoggedIn: true,
+  isSignedIn: true,
+  isLoading: false,
+  loading: false,
+  isPending: false,
+  isRefreshing: false,
+  isInitialized: true,
+  isReady: true,
+  error: null,
+  theme: 'light',
+  colorScheme: 'light',
+  isDark: false,
+  dark: false,
+  colors: previewColorsProxy,
+  items: STABLE_EMPTY_ARRAY,
+  cart: STABLE_EMPTY_ARRAY,
+  favorites: STABLE_EMPTY_ARRAY,
+  wishlist: STABLE_EMPTY_ARRAY,
+  notifications: STABLE_EMPTY_ARRAY,
+  bookings: STABLE_EMPTY_ARRAY,
+  listings: STABLE_EMPTY_ARRAY,
+  vehicles: STABLE_EMPTY_ARRAY,
+  cars: STABLE_EMPTY_ARRAY,
+  orders: STABLE_EMPTY_ARRAY,
+  transactions: STABLE_EMPTY_ARRAY,
+  messages: STABLE_EMPTY_ARRAY,
+  chats: STABLE_EMPTY_ARRAY,
+  unreadCount: 0,
+  count: 0,
+  total: 0,
+  balance: 0,
+  signIn: async () => ({ data: { user: previewUserProxy }, error: null }),
+  signUp: async () => ({ data: { user: previewUserProxy }, error: null }),
+  signOut: async () => ({ error: null }),
+  login: async () => ({ data: { user: previewUserProxy }, error: null }),
+  logout: async () => undefined,
+  register: async () => ({ data: { user: previewUserProxy }, error: null }),
+  refresh: async () => undefined,
+  refetch: async () => undefined,
+  updateProfile: async () => ({ error: null }),
+  toggleTheme: () => undefined,
+  setTheme: () => undefined,
+};
+
+export const SAFE_CONTEXT_FALLBACK: Record<string, unknown> = new Proxy(safeContextFallbackBase, {
+  get(target, prop) {
+    if (prop in target) return target[prop as keyof typeof target];
+    if (prop === Symbol.iterator) {
+      return function* () {
+        yield SAFE_CONTEXT_FALLBACK;
+        yield () => undefined;
+      };
+    }
+    return SAFE_CHAINABLE_PROXY;
+  },
+});
+
+// Install unmounted user-context fallback on React.createContext & React.useContext
+// (runs after react-native-web has already initialized its internal VirtualizedListContext)
+const origCreateContext = React.createContext;
+const origUseContext = React.useContext;
+
+const wrappedCreateContext = function zeluneCreateContext(
+  defaultValue: unknown,
+  ...rest: unknown[]
+) {
+  const isEmptyDefault =
+    defaultValue === undefined ||
+    defaultValue === null ||
+    (typeof defaultValue === 'object' &&
+      defaultValue !== null &&
+      Object.keys(defaultValue as object).length === 0);
+  const effectiveDefault = isEmptyDefault ? SAFE_CONTEXT_FALLBACK : defaultValue;
+  const ctx = (origCreateContext as (...a: unknown[]) => Record<string, unknown>).call(
+    React,
+    effectiveDefault,
+    ...rest
+  );
+  if (ctx && typeof ctx === 'object' && isEmptyDefault) {
+    ctx.__zeluneUserContext = true;
+  }
+  return ctx;
+} as unknown as typeof React.createContext;
+
+const wrappedUseContext = function zeluneUseContext(
+  Context: React.Context<unknown>,
+  ...rest: unknown[]
+) {
+  const val = (origUseContext as (...a: unknown[]) => unknown).call(React, Context, ...rest);
+  if (
+    val === undefined ||
+    (val === null &&
+      Boolean((Context as unknown as Record<string, unknown>)?.__zeluneUserContext))
+  ) {
+    return SAFE_CONTEXT_FALLBACK;
+  }
+  return val;
+} as unknown as typeof React.useContext;
+
+try {
+  React.createContext = wrappedCreateContext;
+  React.useContext = wrappedUseContext;
+} catch {
+  // Ignore if React namespace is frozen in test environment
+}
+
 function createSupabaseQueryBuilder(): Record<string, unknown> {
   const resultPromise = Promise.resolve({ data: [], error: null, count: 0 });
   const builder: Record<string, unknown> = new Proxy(
@@ -1146,6 +1574,29 @@ const defaultExportProperties = {
   useInfiniteQuery,
   useMutation,
   createClient,
+  z,
+  string,
+  number,
+  boolean,
+  object,
+  array,
+  union,
+  literal,
+  record,
+  tuple,
+  any,
+  unknown,
+  optional,
+  nullable,
+  coerce,
+  zodResolver,
+  yupResolver,
+  useForm,
+  useFormContext,
+  FormProvider,
+  useWatch,
+  useFieldArray,
+  Controller,
 };
 
 Object.assign(UniversalDefaultExportComponent, defaultExportProperties);
@@ -1161,7 +1612,7 @@ const defaultExportProxy = new Proxy(UniversalDefaultExportComponent, {
     if (typeof prop === 'string' && /^[A-Z]/.test(prop)) {
       return createVectorIconComponent(prop);
     }
-    return () => undefined;
+    return SAFE_CHAINABLE_PROXY;
   },
 });