aniview 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -1,21 +1,40 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [1.0.0] - 2026-02-10
-
-### Added
-
-- `Aniview` — core animated component with spatial and event-driven keyframes
-- `AniviewProvider` — context provider with gesture handling and spring physics
-- `AniviewConfig` — 2D grid layout engine with page mapping, overlaps, and adjacency graphs
-- `AniviewPanel` / `PanelFrame` — pre-styled panel components
-- `useAniview` — hook to access Aniview context (dimensions, events, config)
-- `useAniviewLock` — hook for directional gesture locking
-- Smart color interpolation (transparent-aware, no gray artifacts)
-- Pre-computed animation grid (zero runtime frame searches)
-- Worklet-optimized rendering (UI thread only)
-- Full TypeScript type definitions
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.1] - 2026-06-09
+
+### Added
+
+- Core animation baking, color interpolation, gesture, and style helpers split into focused modules under `src/core/`.
+- Regression tests for frame baking, color interpolation, lock masks, math helpers, and snapshots.
+- Local development guide for testing Aniview from a consumer React Native app with Metro module de-duplication.
+
+### Changed
+
+- Refreshed README, Getting Started, Core Concepts, API Reference, Performance, Testing, Gesture Control, Reporting Issues, and Docusaurus docs to match the current public API.
+- Updated development dependencies for the current React Native/Reanimated test setup.
+- Improved snapshot test setup for the current React test renderer behavior.
+- Clarified `persistent` component mounting versus `eventPersistent` event-frame weighting.
+
+### Fixed
+
+- Corrected directional lock-mask handling so `AniviewLock.mask({ left, right, up, down })` matches provider gesture behavior.
+- Removed stale Docusaurus/template documentation language and broken documentation links.
+
+## [1.0.0] - 2026-02-10
+
+### Added
+
+- `Aniview` — core animated component with spatial and event-driven keyframes
+- `AniviewProvider` — context provider with gesture handling and spring physics
+- `AniviewConfig` — 2D grid layout engine with page mapping, overlaps, and adjacency graphs
+- `useAniview` — hook to access Aniview context (dimensions, events, config)
+- `useAniviewLock` — hook for directional gesture locking
+- Smart color interpolation (transparent-aware, no gray artifacts)
+- Pre-computed animation grid (zero runtime frame searches)
+- Worklet-optimized rendering (UI thread only)
+- Full TypeScript type definitions

package/README.md

@@ -4,127 +4,123 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![React Native](https://img.shields.io/badge/React%20Native-%3E%3D0.71-blue)](https://reactnative.dev/)
 
-> A high-performance, coordinate-based animation engine for React Native. Create fluid, multi-dimensional page transitions with spatial and event-driven animations.
+Aniview is a coordinate-based animation and page-navigation engine for React Native. It lets you describe a 2D page world, place components on named pages, and define style frames that interpolate as the camera moves between pages or as custom Reanimated `SharedValue`s change.
 
-## Features
+## What it is good for
 
-- **Pre-computed Animation Grid** - Zero runtime frame searches
-- **Spatial & Event-Driven** - Animate based on position OR custom events
-- **Gesture Coordination** - Built-in lock system for complex UI interactions
-- **Smart Color Interpolation** - Transparent-aware color transitions
-- **Worklet-Optimized** - Runs entirely on the UI thread
-- **2D Layout Engine** - Grid-based page navigation with overlap support
-- **TypeScript First** - Full type safety out of the box
+- Swipeable multi-page interfaces that are not just a flat carousel.
+- Components that morph between pages without imperative animation code.
+- Event-driven effects such as scroll, zoom, or progress-linked animation.
+- React Native apps that need gesture coordination between page swipes and nested interactions.
+- Persistent animated surfaces such as video, canvas, or GL content that must not unmount offscreen.
 
-## Quick Start
+## Install
+
+Aniview expects a working React Native app with Reanimated and React Native Gesture Handler configured.
 
 ```bash
 npm install aniview react-native-reanimated react-native-gesture-handler
 ```
 
-### Basic Example
-
-```tsx
-import { AniviewProvider, Aniview } from "aniview";
-
-// 1. Define your layout (3x3 grid)
-const config = new AniviewConfig(
-  [
-    [1, 1, 1],
-    [1, 1, 1],
-    [1, 1, 1],
-  ],
-  0, // default page
-  { HOME: 0, PROFILE: 1, SETTINGS: 2 }, // page map
-);
-
-// 2. Wrap your app
-function App() {
-  return (
-    <AniviewProvider config={config}>
-      <Header />
-      <Content />
-    </AniviewProvider>
-  );
-}
+For Expo projects, prefer Expo's version resolver for the peer dependencies:
 
-// 3. Animate components
-function Header() {
-  return (
-    <Aniview
-      pageId="HOME"
-      frames={{
-        profile: {
-          page: "PROFILE",
-          style: { backgroundColor: "blue" },
-        },
-      }}
-      style={{ height: 100, backgroundColor: "white" }}
-    >
-      <Text>My Header</Text>
-    </Aniview>
-  );
-}
+```bash
+npx expo install react-native-reanimated react-native-gesture-handler
+npm install aniview
 ```
 
-## Documentation
+Make sure the Reanimated Babel plugin is configured according to the Reanimated docs for your app.
 
-- **[Getting Started](docs/01-getting-started.md)** - Installation and first steps
-- **[Core Concepts](docs/02-core-concepts.md)** - Understanding the architecture
-- **[API Reference](docs/03-api-reference.md)** - Complete API documentation
-- **[Advanced Patterns](docs/04-advanced-patterns.md)** - Composition, Persistence & Virtualization
-- **[Examples & Recipes](docs/05-examples.md)** - Full Example App Walkthrough
-- **[Performance Guide](docs/06-performance.md)** - Optimization techniques
-- **[Testing](docs/07-testing.md)** - How to test Aniview components
-- **[Gesture Control](docs/08-gesture-control.md)** - Lock system and gesture coordination
-- **[Reporting Issues](docs/09-reporting-issues.md)** - Bug reports and feature requests
+## Minimal Example
 
-## Key Concepts
+```tsx
+import React from "react";
+import { Text, StyleSheet } from "react-native";
+import { GestureHandlerRootView } from "react-native-gesture-handler";
+import { Aniview, AniviewProvider } from "aniview";
 
-### The Grid System
+const pageMap = {
+  HOME: 0,
+  PROFILE: 1,
+};
 
-Aniview uses a **2D grid layout** where each cell represents a "page":
+export default function App() {
+  return (
+    <GestureHandlerRootView style={styles.root}>
+      <AniviewProvider layout={[[1, 1]]} pageMap={pageMap} defaultPage="HOME">
+        <Aniview pageId="HOME" style={[styles.page, styles.home]}>
+          <Text style={styles.title}>Home</Text>
+        </Aniview>
+
+        <Aniview pageId="PROFILE" style={[styles.page, styles.profile]}>
+          <Text style={styles.title}>Profile</Text>
+        </Aniview>
+
+        <Aniview
+          pageId="HOME"
+          style={styles.badge}
+          frames={{
+            atProfile: {
+              page: "PROFILE",
+              style: {
+                backgroundColor: "#e91e63",
+                transform: [{ scale: 1.4 }],
+              },
+            },
+          }}
+        />
+      </AniviewProvider>
+    </GestureHandlerRootView>
+  );
+}
 
+const styles = StyleSheet.create({
+  root: { flex: 1 },
+  page: {
+    width: "100%",
+    height: "100%",
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  home: { backgroundColor: "#e3f2fd" },
+  profile: { backgroundColor: "#fce4ec" },
+  title: { fontSize: 32, fontWeight: "700" },
+  badge: {
+    width: 72,
+    height: 72,
+    borderRadius: 36,
+    backgroundColor: "#2196f3",
+    left: 32,
+    top: 64,
+  },
+});
 ```
-[0, 1, 2]  →  Pages 0, 1, 2 (horizontal row)
-[3, 4, 5]  →  Pages 3, 4, 5 (second row)
-```
-
-Components declare where they "live" (`pageId`) and how they transform when navigating to other pages (`frames`).
-
-### Animation Types
 
-1. **Spatial Animations** - Triggered by page navigation (X/Y position)
-2. **Event-Driven Animations** - Triggered by custom SharedValues (scroll, zoom, etc.)
+Swipe horizontally to move between `HOME` and `PROFILE`. The badge belongs to `HOME`, but its frame describes how it should look when the camera reaches `PROFILE`.
 
-### The Baking Process
-
-On mount, Aniview:
-
-1. Pre-computes a **grid of all possible states**
-2. Organizes them into **horizontal and vertical lanes**
-3. Marks **constant values** to skip interpolation
-4. All this happens **once**, not on every frame
+## Documentation
 
-## Platform Support
+- [Getting Started](docs/01-getting-started.md) - Installation and first working app
+- [Core Concepts](docs/02-core-concepts.md) - Coordinate space, pages, frames, baking, and virtualization
+- [API Reference](docs/03-api-reference.md) - Public components, hooks, methods, and types
+- [Advanced Patterns](docs/04-advanced-patterns.md) - Composition, persistence, and event-driven patterns
+- [Examples & Recipes](docs/05-examples.md) - Larger examples and interaction recipes
+- [Performance Guide](docs/06-performance.md) - Optimization techniques
+- [Testing](docs/07-testing.md) - Testing Aniview logic and components
+- [Gesture Control](docs/08-gesture-control.md) - Gesture toggles, locks, and simultaneous handlers
+- [Reporting Issues](docs/09-reporting-issues.md) - Bug reports and feature requests
+- [Local Development](LOCAL_DEV.md) - Using a local checkout from a React Native app
 
-Aniview is designed for **React Native** (iOS and Android). It is compatible with:
+## Mental Model
 
-- **Expo** managed workflow (SDK 49+)
-- **React Native CLI** projects
-- **New Architecture** (Fabric) — fully compatible (pure JS/TS + Reanimated worklets)
+Aniview has three moving parts:
 
-## Contributing
+1. `AniviewProvider` owns the camera, dimensions, page layout, gesture handler, and custom event shared values.
+2. `AniviewConfig` maps page IDs to world coordinates and builds gesture/navigation rules.
+3. `Aniview` components declare a home page plus optional spatial or event frames. On mount, frames are baked into interpolation lanes consumed by Reanimated worklets.
 
-We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+The important composition rule: use sibling `Aniview` components for world-positioned elements. Nest `Aniview` components only when you intentionally want parent and child transforms to combine.
 
 ## License
 
-MIT © Madelyn Cruz Tan
-
-## Credits
-
-Built with:
-
-- [react-native-reanimated](https://github.com/software-mansion/react-native-reanimated)
-- [react-native-gesture-handler](https://github.com/software-mansion/react-native-gesture-handler)
+MIT (c) Madelyn Cruz Tan (TitanicEclair)

package/dist/Aniview.d.ts

@@ -40,6 +40,7 @@ import { AniviewProps } from './useAniviewContext';
  * @param props.persistent - If `true`, stays mounted even when far offscreen. Required for WebGL/Three.js canvases. Default: `false`
  * @param props.style - Base styles applied when at home position. Numeric and color props here become the interpolation baseline.
  * @param props.pointerEvents - Standard RN pointer events. Useful for overlay pages that shouldn't block touches.
+ * @returns Animated view that interpolates styles from spatial and event lanes.
  *
  * @example
  * ```tsx

package/dist/Aniview.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Aniview.d.ts","sourceRoot":"","sources":["../src/Aniview.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAoD,MAAM,OAAO,CAAC;AAUzE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAiMnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,MAAM,CAAC,OAAO,UAAU,OAAO,CAAC,KAAK,EAAE,YAAY,4BA6lBlD"}
+{"version":3,"file":"Aniview.d.ts","sourceRoot":"","sources":["../src/Aniview.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAoD,MAAM,OAAO,CAAC;AAOzE,OAAO,EAAE,YAAY,EAAe,MAAM,qBAAqB,CAAC;AAKhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,MAAM,CAAC,OAAO,UAAU,OAAO,CAAC,KAAK,EAAE,YAAY,4BAsIlD"}