aniview 1.0.0

package/src/aniviewProvider.tsx

@@ -0,0 +1,307 @@
+import React, { useMemo, useEffect, useRef, useState, useImperativeHandle, forwardRef } from 'react';
+import { LayoutChangeEvent, View, Dimensions as RNDimensions, LayoutRectangle } from 'react-native';
+import Animated, { useSharedValue, withSpring, makeMutable, SharedValue, WithSpringConfig } from 'react-native-reanimated';
+import { AniviewContext, AniviewContextType, AniviewHandle, AniviewFrame, BakedFrame, IAniviewConfig, WorldBounds } from "./useAniviewContext";
+import { AniviewConfig } from './aniviewConfig';
+import { GestureDetector, PanGesture } from 'react-native-gesture-handler';
+import * as AniviewMath from './core/AniviewMath';
+
+export interface AniviewProviderProps {
+  children: React.ReactNode;
+  /** Explicitly provide a config instance (Advanced) */
+  config?: AniviewConfig;
+  /** The grid layout matrix (e.g., [[1, 1, 1, 1]]) - Simple setup */
+  layout?: number[][];
+  /** The source-of-truth origin page */
+  defaultPage?: number;
+  /** Explicitly override page size. Defaults to container size. */
+  pageSize?: { width: number; height: number };
+  /** Callback when page changes */
+  onPageChange?: (pageId: number | string) => void;
+  /** Imperative active page control (Legacy) - prefer ref.snapToPage */
+  activePage?: number | string;
+  /** Map of semantic names to numeric page IDs */
+  pageMap?: Record<string, number>;
+  /** External ref for the internal PanGesture (for coordination) */
+  gestureRef?: React.RefObject<any>;
+  /** Custom spring physics */
+  springConfig?: WithSpringConfig;
+  /** External events to drive animations */
+  events?: Record<string, SharedValue<number>>;
+  /** Explicit dimensions override */
+  dimensions?: Partial<AniviewContextType['dimensions']>;
+  /** External lockMask for gesture coordination */
+  externalLockMask?: SharedValue<number>;
+  /** External gesture enabled control (simple on/off) */
+  gestureEnabled?: SharedValue<boolean>;
+  /** Simultaneous gesture handlers for coordination */
+  simultaneousHandlers?: any;
+}
+
+/**
+ * **AniviewProvider** — World Coordinate System & Gesture Controller
+ *
+ * The root provider that establishes the virtual 2D world in which all
+ * child `Aniview` components live. It manages:
+ *
+ * - **The Camera** (`events.x`, `events.y` SharedValues) — the current
+ *   viewport position in world coordinates, driven by gestures or
+ *   programmatic `snapToPage` calls.
+ * - **Pan Gesture** — a RNGH Pan gesture that translates finger movement
+ *   into camera position updates, with axis locking, edge resistance,
+ *   velocity-based snapping, and bitmask-based directional locks.
+ * - **Virtualization** — tracks which pages are "near" the camera and
+ *   provides a `visiblePages` set for child components.
+ * - **Custom Events** — user-supplied SharedValues (e.g., scroll position,
+ *   slider value) that drive event-based keyframe animations.
+ *
+ * ### Sizing behavior
+ *
+ * By default, the provider measures its own container via `onLayout`
+ * and uses that as the page size. Override with `pageSize` or
+ * `dimensions` if you need explicit control (e.g., for offscreen pages
+ * that are larger than the visible container).
+ *
+ * ### Imperative API
+ *
+ * Attach a `ref` to access `snapToPage(pageId)`, `getCurrentPage()`,
+ * and `lock(mask)` for programmatic navigation.
+ *
+ * @param props.config - Pre-built `AniviewConfig` instance (advanced). Mutually exclusive with `layout`.
+ * @param props.layout - Grid matrix (e.g., `[[1, 1, 1]]` for 3 horizontal pages). Creates an `AniviewConfig` internally.
+ * @param props.defaultPage - The initial page ID (default: `0`).
+ * @param props.pageMap - Semantic name → numeric ID mapping (e.g., `{ HOME: 0, SETTINGS: 1 }`).
+ * @param props.pageSize - Explicit page dimensions. If omitted, inferred from container layout.
+ * @param props.onPageChange - Fires when the camera snaps to a new page.
+ * @param props.springConfig - Custom spring physics for snap animations.
+ * @param props.events - Additional SharedValues that drive event-based keyframes.
+ * @param props.externalLockMask - Externally controlled bitmask SharedValue for gesture locking. See {@link useAniviewLock}.
+ * @param props.gestureEnabled - SharedValue to globally enable/disable the pan gesture.
+ * @param props.simultaneousHandlers - RNGH refs for gesture coordination with parent/sibling handlers.
+ * @param props.activePage - (Legacy) Declarative page control. Prefer `ref.snapToPage()`.
+ *
+ * @example
+ * ```tsx
+ * const config = new AniviewConfig([[1, 1, 1]], 0, { HOME: 0, FEED: 1, PROFILE: 2 });
+ * const scrollY = useSharedValue(0);
+ *
+ * <AniviewProvider ref={aniviewRef} config={config} events={{ scrollY }} onPageChange={setPage}>
+ *   <Aniview pageId="HOME">...</Aniview>
+ *   <Aniview pageId="FEED">...</Aniview>
+ * </AniviewProvider>
+ * ```
+ */
+export const AniviewProvider = forwardRef<AniviewHandle, AniviewProviderProps>(({
+  children,
+  config: providedConfig,
+  layout,
+  defaultPage = 0,
+  pageSize,
+  onPageChange,
+  activePage,
+  gestureRef,
+  springConfig,
+  events: externalEvents,
+  pageMap = {},
+  dimensions: providedDims,
+  externalLockMask,
+  gestureEnabled: externalGestureEnabled,
+  simultaneousHandlers
+}: AniviewProviderProps, ref: React.Ref<AniviewHandle>) => {
+  // --- CONFIG MANAGEMENT ---
+  const config = useMemo(() => {
+    if (providedConfig) return providedConfig;
+    if (layout) return new AniviewConfig(layout, defaultPage, pageMap, {}, {}, {});
+    return new AniviewConfig([[1]], 0, pageMap, {}, {}, {}); // Fallback
+  }, [providedConfig, layout, defaultPage, pageMap]);
+
+  // --- STATE & PHYSICS ---
+  const x = useSharedValue(0);
+  const y = useSharedValue(0);
+  
+  // Use external lockMask if provided, otherwise create internal one
+  const internalLockMask = useSharedValue(0);
+  const lockMask = externalLockMask || internalLockMask;
+  
+  // Use external gestureEnabled if provided, otherwise create internal one
+  const internalGestureEnabled = useSharedValue(true);
+  const gestureEnabled = externalGestureEnabled || internalGestureEnabled;
+  const lastTargetId = useSharedValue<number | string>(config.defaultPage);
+  const isMoving = useSharedValue(false);
+  
+  const [dimensions, setDimensions] = useState<AniviewContextType['dimensions']>({
+    width: providedDims?.width ?? pageSize?.width ?? 0,
+    height: providedDims?.height ?? pageSize?.height ?? 0,
+    offsetX: providedDims?.offsetX ?? 0,
+    offsetY: providedDims?.offsetY ?? 0
+  });
+
+  // --- VIRTUALIZATION STATE ---
+  // Tracks which pages are near the "viewport" on the JS thread
+  // We use a ref and a forced refresh ONLY when absolutely needed to prevent 
+  // every Aniview component from re-rendering on every page traversal.
+  const visiblePagesRef = useRef<Set<number>>(new Set([config.resolvePageId(defaultPage)]));
+
+  const updateVisibility = (centerPage: number | string) => {
+    const visible = new Set<number>();
+    const pages = config.getPages();
+    const resolvedCenter = config.resolvePageId(centerPage);
+    const centerPos = AniviewMath.pageIdToMatrixPos(resolvedCenter, (config as any).layout);
+
+    pages.forEach((p: number) => {
+        const pPos = AniviewMath.pageIdToMatrixPos(p, (config as any).layout);
+        const rowDist = Math.abs(pPos.r - centerPos.r);
+        const colDist = Math.abs(pPos.c - centerPos.c);
+        if (rowDist <= 1 && colDist <= 1) visible.add(p);
+    });
+
+    const current = visiblePagesRef.current;
+    if (current.size !== visible.size || ![...visible].every(v => current.has(v))) {
+        visiblePagesRef.current = visible;
+        // Optimization: NO BROADCAST. 
+        // We rely on the native proxy for virtualization checks within worklets.
+    }
+  };
+
+  // Sync the SharedValue target into the config engine for virtualization worklets
+  useEffect(() => {
+    if ((config as any)._setCurrentPageSV) {
+      (config as any)._setCurrentPageSV(lastTargetId);
+    }
+  }, [config, lastTargetId]);
+
+  // --- IMPERATIVE API ---
+  useImperativeHandle(ref, () => ({
+    snapToPage: (pageId: number | string) => {
+      const offset = config.getPageOffset(pageId, dimensions);
+      const springConfig = config.getSpringConfig();
+      
+      isMoving.value = true;
+      x.value = withSpring(offset.x, springConfig, (finished) => {
+        if (finished) isMoving.value = false;
+      });
+      y.value = withSpring(offset.y, springConfig);
+      
+      lastTargetId.value = pageId;
+      updateVisibility(pageId);
+      if (onPageChange) onPageChange(pageId);
+    },
+    getCurrentPage: () => lastTargetId.value,
+    lock: (mask: number) => { lockMask.value = mask; }
+  }));
+
+  // --- DYNAMIC UPDATES ---
+  useEffect(() => {
+    if (springConfig) config.updateSpringConfig(springConfig);
+  }, [springConfig, config]);
+
+  useEffect(() => {
+    config.updateDimensions(dimensions);
+  }, [dimensions, config]);
+
+  // --- ONLAYOUT AUTO-SIZING ---
+  const onLayout = (e: LayoutChangeEvent) => {
+    const { width, height, x: layoutX, y: layoutY } = e.nativeEvent.layout;
+    
+    // Only update if dimensions drastically changed (debounce/diff)
+    if (
+      Math.abs(width - dimensions.width) > 1 || 
+      Math.abs(height - dimensions.height) > 1 ||
+      Math.abs(layoutX - dimensions.offsetX) > 1 ||
+      Math.abs(layoutY - dimensions.offsetY) > 1
+    ) {
+      setDimensions(prev => ({
+        ...prev,
+        width: providedDims?.width ?? (pageSize?.width || width),
+        height: providedDims?.height ?? (pageSize?.height || height),
+        offsetX: layoutX,
+        offsetY: layoutY
+      }));
+    }
+  };
+
+  // --- VIRTUALIZATION ---
+  const activationMap = useMemo(() => {
+    const map: Record<number, any> = {};
+    config.getPages().forEach(id => {
+      map[id] = makeMutable(1);
+    });
+    return map;
+  }, [config]);
+
+  // --- BOOTSTRAPPING ---
+  useEffect(() => {
+    if (config) {
+      const offset = config.getPageOffset(config.defaultPage, dimensions);
+      x.value = offset.x;
+      y.value = offset.y;
+      lastTargetId.value = config.defaultPage;
+    }
+  }, [config]);
+
+  // --- LEGACY TAB SYNC ---
+  useEffect(() => {
+    if (config && activePage !== undefined) {
+      if (lastTargetId.value === activePage) return;
+      const offset = config.getPageOffset(activePage, dimensions);
+      const isMoved = Math.abs(x.value - offset.x) > 1 || Math.abs(y.value - offset.y) > 1;
+
+      if (isMoved) {
+        const physics = config.getSpringConfig();
+        isMoving.value = true;
+        x.value = withSpring(offset.x, physics, (finished) => {
+          if (finished) isMoving.value = false;
+        });
+        y.value = withSpring(offset.y, physics);
+        lastTargetId.value = activePage;
+      }
+    }
+  }, [activePage, config]);
+
+  // --- GESTURE ---
+  // We recreate the gesture when key dependencies change. 
+  // Ideally this should be stable, but config.generateGesture needs latest dims logic if re-run.
+  const panGesture = useMemo(() => {
+    return config.generateGesture(
+      x, 
+      y, 
+      (pageId) => {
+        lastTargetId.value = pageId;
+        updateVisibility(pageId);
+        if (onPageChange) onPageChange(pageId);
+      }, 
+      lockMask,
+      simultaneousHandlers,
+      gestureEnabled,
+      dimensions,
+      isMoving,
+      lastTargetId
+    );
+  }, [config, x, y, lockMask, onPageChange, dimensions, isMoving]); // Force rebuild when dimensions hit bitumen
+
+  if (gestureRef) {
+    (panGesture as any).ref = gestureRef;
+  }
+
+  const contextValue = useMemo(() => ({
+    dimensions,
+    events: { x, y, ...(externalEvents || {}) },
+    activationMap,
+    panGesture,
+    config,
+    lock: (mask: number) => { lockMask.value = mask; },
+    visiblePages: visiblePagesRef.current,
+    isMoving
+  }), [dimensions, x, y, externalEvents, activationMap, config, panGesture, lockMask]);
+
+  return (
+    <AniviewContext.Provider value={contextValue}>
+      <GestureDetector gesture={panGesture}>
+        {/* The Stage */}
+        <Animated.View style={{ flex: 1 }} onLayout={onLayout}>
+          {children}
+        </Animated.View>
+      </GestureDetector>
+    </AniviewContext.Provider>
+  );
+});

package/src/core/AniviewLock.ts

@@ -0,0 +1,23 @@
+/**
+ * Valid directions for locking Aniview gestures.
+ */
+export type AniviewAxisLock = {
+    left?: boolean;
+    right?: boolean;
+    up?: boolean;
+    down?: boolean;
+}
+
+/**
+ * Utility to generate Aniview lock bitmasks.
+ */
+export const AniviewLock = {
+    mask: (directions: AniviewAxisLock) => {
+        let mask = 0;
+        if (directions.left) mask |= 1;
+        if (directions.right) mask |= 2;
+        if (directions.up) mask |= 4;
+        if (directions.down) mask |= 8;
+        return mask;
+    }
+};

package/src/core/AniviewMath.ts

@@ -0,0 +1,107 @@
+/**
+ * ANIVIEW MATH CORE
+ * 
+ * Pure functional implementation of Aniview's spatial logic.
+ */
+
+export interface MatrixPos {
+  r: number;
+  c: number;
+}
+
+export interface WorldBounds {
+  minX: number;
+  maxX: number;
+  minY: number;
+  maxY: number;
+}
+
+/**
+ * Converts a linear PageID to a (Row, Column) matrix position.
+ */
+export function pageIdToMatrixPos(pageId: number, layout: number[][]): MatrixPos {
+  'worklet';
+  const rowLength = Math.max(1, layout[0]?.length || 0);
+  const numRows = layout.length;
+  const maxPage = numRows * rowLength - 1;
+  
+  if (pageId < 0 || pageId > maxPage) {
+    return { r: 9999, c: 9999 };
+  }
+
+  return {
+    r: Math.floor(pageId / rowLength),
+    c: pageId % rowLength
+  };
+}
+
+/**
+ * Calculates the displacement between two indices on an axis, accounting for overlaps.
+ */
+export function calculateAxisOffset(
+  from: number, 
+  to: number, 
+  size: number, 
+  overlaps: number[]
+): number {
+  'worklet';
+  if (from === to) return 0;
+  const direction = to > from ? 1 : -1;
+  let totalOffset = 0;
+  const start = Math.min(from, to);
+  const end = Math.max(from, to);
+  for (let i = start; i < end; i++) {
+    const overlapRatio = overlaps[i] || 0;
+    totalOffset += size * (1 - overlapRatio);
+  }
+  return totalOffset * direction;
+}
+
+/**
+ * Calculates the (x, y) coordinates of a page relative to a default origin page.
+ */
+export function getPageOffset(
+  pageId: number,
+  layout: number[][],
+  contextDims: { width: number; height: number },
+  defaultPage: number,
+  rowOverlaps: number[],
+  colOverlaps: number[]
+): { x: number; y: number } {
+  'worklet';
+  const target = pageIdToMatrixPos(pageId, layout);
+  const origin = pageIdToMatrixPos(defaultPage, layout);
+  
+  return {
+    x: calculateAxisOffset(origin.c, target.c, contextDims.width, colOverlaps),
+    y: calculateAxisOffset(origin.r, target.r, contextDims.height, rowOverlaps)
+  };
+}
+
+/**
+ * Calculates the absolute boundaries of the virtual world.
+ */
+export function getWorldBounds(
+  pages: number[],
+  layout: number[][],
+  contextDims: { width: number; height: number },
+  defaultPage: number,
+  rowOverlaps: number[],
+  colOverlaps: number[]
+): WorldBounds {
+  'worklet';
+  if (pages.length === 0) return { minX: 0, maxX: 0, minY: 0, maxY: 0 };
+  
+  const firstOffset = getPageOffset(pages[0], layout, contextDims, defaultPage, rowOverlaps, colOverlaps);
+  let minX = firstOffset.x, maxX = firstOffset.x, minY = firstOffset.y, maxY = firstOffset.y;
+
+  for (let i = 1; i < pages.length; i++) {
+    const offset = getPageOffset(pages[i], layout, contextDims, defaultPage, rowOverlaps, colOverlaps);
+    minX = Math.min(minX, offset.x);
+    maxX = Math.max(maxX, offset.x);
+    minY = Math.min(minY, offset.y);
+    maxY = Math.max(maxY, offset.y);
+  }
+
+  return { minX, maxX, minY, maxY };
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { default as Aniview } from './Aniview';
+export { AniviewProvider } from './aniviewProvider';
+export { AniviewConfig } from './aniviewConfig';
+export { useAniview } from './useAniview';
+export { useAniviewLock, AniviewLock } from './useAniviewLock';
+export * from './useAniviewContext';

package/src/useAniview.tsx

@@ -0,0 +1,75 @@
+import * as React from 'react';
+import { useContext } from 'react';
+import { AniviewContext, AniviewProps, AniviewLogic, AniviewContextType } from "./useAniviewContext";
+
+/**
+ * **useAniview** — Access the Aniview world context
+ *
+ * This hook has two overloads:
+ *
+ * **1. Context-only** (`useAniview()`) — Returns the raw {@link AniviewContextType}
+ * containing the camera SharedValues, config, dimensions, and gesture state.
+ * Use this when you need to read the camera position or react to page changes
+ * without being an animated component yourself.
+ *
+ * **2. Per-component** (`useAniview(props)`) — Used internally by `Aniview`
+ * components. Registers the component's `pageId` with the config engine and
+ * returns an {@link AniviewLogic} object containing the resolved registration,
+ * activation value, and keyframes. You rarely need this overload directly.
+ *
+ * @returns When called without arguments: `{ dimensions, events, config, activationMap, panGesture, visiblePages, isMoving }`
+ * @returns When called with props: `AniviewLogic` with additional `registration`, `activationValue`, and `keyframes`
+ *
+ * @throws Error if called outside of an `<AniviewProvider />`
+ *
+ * @example
+ * ```tsx
+ * // Read camera position from any child
+ * function CameraDebug() {
+ *   const { events } = useAniview();
+ *   // events.x.value, events.y.value are the camera world coordinates
+ * }
+ *
+ * // React to custom events
+ * function ScrollReactor() {
+ *   const { events } = useAniview();
+ *   // events.scrollY?.value (if parent passed events={{ scrollY }})
+ * }
+ * ```
+ */
+export function useAniview(): AniviewContextType;
+export function useAniview(props: AniviewProps): AniviewLogic;
+export function useAniview(props?: AniviewProps): AniviewContextType | AniviewLogic {
+  const context = useContext(AniviewContext);
+  if (!context) {
+    throw new Error('Aniview components must be wrapped in an <AniviewProvider />');
+  }
+
+  // If no props provided, just return the raw context
+  if (!props || typeof props !== 'object') return context;
+
+  const pageId = props.pageId;
+
+  const registration = context.config ? context.config.registerPage(pageId, context.dimensions) : {
+    offset: { x: 0, y: 0 },
+    dimensions: context.dimensions
+  };
+
+  const activationValue = (context.activationMap && pageId !== undefined) ? (context.activationMap as any)[pageId] : null;
+
+  const logic: AniviewLogic = {
+    dimensions: context.dimensions,
+    events: context.events,
+    activationMap: context.activationMap,
+    panGesture: context.panGesture,
+    config: context.config,
+    registration: registration as any,
+    activationValue: activationValue as any,
+    keyframes: props.frames as any,
+    lock: context.lock,
+    visiblePages: context.visiblePages,
+    isMoving: context.isMoving,
+  };
+
+  return logic;
+}

package/src/useAniviewContext.tsx

@@ -0,0 +1,170 @@
+import React, { createContext } from "react";
+import { SharedValue, AnimatedProps, WithSpringConfig } from "react-native-reanimated";
+import { PanGesture } from "react-native-gesture-handler";
+import { ViewProps, ViewStyle } from "react-native";
+import { WorldBounds } from "./core/AniviewMath";
+
+export type { WorldBounds };
+
+/**
+ * ANIVIEW DOMAIN TYPES
+ */
+export interface AniviewFrame {
+  /** Target page ID for spatial transitions (can be numeric index or semantic name) */
+  page?: number | string;
+  /** Custom event name for state-driven transitions (e.g., 'zoom', 'tilt') */
+  event?: string;
+  /** The value of the event driver that triggers this frame */
+  value?: number;
+  /** Style overrides for this frame */
+  style?: ViewStyle | ViewStyle[];
+  /** 
+   * If true, this event-driven frame remains active across all pages.
+   * If false (default), the effect is modulated by proximity to the component's home page.
+   */
+  persistent?: boolean;
+  /** Optional opacity override shortcut */
+  opacity?: number;
+  /** Optional scale override shortcut */
+  scale?: number;
+  /** Optional rotate (Z) override shortcut (degrees) */
+  rotate?: number;
+  /** Spring config override for this specific frame transition (future) */
+  springConfig?: any;
+}
+
+export interface BakedFrame extends AniviewFrame {
+  worldX: number;
+  worldY: number;
+}
+
+export interface AniviewRegistration {
+  offset: { x: number; y: number };
+  dimensions: { width: number; height: number };
+}
+
+export interface AniviewProps extends AnimatedProps<ViewProps> {
+  pageId: number | string;       // The ID of the page this component belongs to
+  frames?: AniviewFrame[] | Record<string, AniviewFrame>; // Supports both Array (New) and Object (Legacy)
+  events?: { 
+    x: SharedValue<number>; 
+    y: SharedValue<number>;
+    [key: string]: SharedValue<number>;
+  } | null;
+  children?: React.ReactNode;
+  style?: ViewStyle | ViewStyle[];
+  pointerEvents?: 'box-none' | 'none' | 'box-only' | 'auto';
+  /** 
+   * If true, this component stays mounted even when offscreen. 
+   * Essential for 3D/GL contexts. 
+   * If false (default), it unmounts when offscreen to save RAM.
+   */
+  persistent?: boolean;
+}
+
+/**
+ * Imperative Handle for controlling the Aniview Physics Engine
+ */
+export interface AniviewHandle {
+  /** Programmatically snap to a specific page */
+  snapToPage: (pageId: number | string) => void;
+  /** Get the current active page ID */
+  getCurrentPage: () => number | string;
+  /** Lock specific axes (bitmask: 1=Left, 2=Right, 4=Up, 8=Down) */
+  lock: (mask: number) => void;
+}
+
+/**
+ * Interface for the Aniview configuration engine.
+ */
+export interface IAniviewConfig {
+  /** Gets the global (x, y) offset for a specific page relative to origin. */
+  getPageOffset(pageId: number | string, dims: AniviewContextType['dimensions']): { x: number; y: number };
+
+  /** 
+   * Pre-calculates absolute coordinates for a component's keyframes.
+   * Executed during the 'Baking' phase on the JS thread.
+   */
+  register(
+    pageId: number | string, 
+    dims: AniviewContextType['dimensions'],
+    keyframes?: AniviewFrame[] | Record<string, AniviewFrame>,
+    localLayout?: { x: number; y: number }
+  ): {
+    homeOffset: { x: number; y: number };
+    bakedFrames: Record<string, BakedFrame>;
+    eventLanes: Record<string, BakedFrame[]>; // Keyed by event name
+    localLayout: { x: number; y: number };
+  };
+
+  /** Minimal offset context for direct page references */
+  registerPage(pageId: number | string, dims: AniviewContextType['dimensions']): AniviewRegistration;
+
+  /** Returns all valid page IDs defined in the layout matrix */
+  getPages(): number[];
+
+  /** Map of PageID -> (x, y) coordinates */
+  getPagesMap(dims: AniviewContextType['dimensions']): Record<number, { x: number; y: number }>;
+
+  /** Returns calculated min/max world boundaries for gesture clamping */
+  getWorldBounds(dims: AniviewContextType['dimensions']): WorldBounds;
+
+  /** Update dimensions dynamically (used by onLayout) */
+  updateDimensions(dims: AniviewContextType['dimensions']): void;
+
+  /** Update spring config dynamically */
+  updateSpringConfig(config: WithSpringConfig): void;
+
+  /** Generates the core Pan Gesture logic */
+  generateGesture(
+    x: SharedValue<number>, 
+    y: SharedValue<number>, 
+    onPageChange?: (pageId: number | string) => void, 
+    lockMask?: SharedValue<number>, 
+    simultaneousHandlers?: any,
+    gestureEnabled?: SharedValue<boolean>,
+    dims?: AniviewContextType['dimensions'],
+    isSnapping?: SharedValue<boolean>,
+    lastTargetId?: SharedValue<number | string>
+  ): any;
+
+  /** Resolves a potentially semantic pageId string into its numeric index */
+  resolvePageId(pageId: number | string): number;
+
+  /** Returns the current active page ID (SharedValue) */
+  getCurrentPage(): SharedValue<number | string>;
+}
+
+export interface AniviewContextType {
+  dimensions: {
+    width: number;
+    height: number;
+    offsetX: number;
+    offsetY: number;
+  }
+  events: {
+    x: SharedValue<number>;
+    y: SharedValue<number>;
+    [key: string]: SharedValue<number>;
+  }
+  activationMap: Record<number, SharedValue<number>>;
+  panGesture: any;
+  config: IAniviewConfig;
+  /** Programmatically lock specific axes */
+  lock: (mask: number) => void;
+  /** Set of page IDs that should currently be mounted */
+  visiblePages: Set<number>;
+  /** Tracks if Aniview is currently snapping/animating toward a page */
+  isMoving: SharedValue<boolean>;
+}
+
+/**
+ * The full logic state for a specific Aniview component.
+ */
+export interface AniviewLogic extends AniviewContextType {
+  registration: AniviewRegistration;
+  activationValue: SharedValue<number>;
+  keyframes: Record<string, AniviewFrame> | undefined;
+}
+
+export const AniviewContext = createContext<AniviewContextType | null>(null);