diff --git a/.env.example b/.env.example deleted file mode 100644 index 7a550fe..0000000 --- a/.env.example +++ /dev/null @@ -1,9 +0,0 @@ -# GEMINI_API_KEY: Required for Gemini AI API calls. -# AI Studio automatically injects this at runtime from user secrets. -# Users configure this via the Secrets panel in the AI Studio UI. -GEMINI_API_KEY="MY_GEMINI_API_KEY" - -# APP_URL: The URL where this applet is hosted. -# AI Studio automatically injects this at runtime with the Cloud Run service URL. -# Used for self-referential links, OAuth callbacks, and API endpoints. -APP_URL="MY_APP_URL" diff --git a/GEMINI.md b/GEMINI.md index eb36080..b667414 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -1,17 +1,17 @@ -# GEMINI.md +# InstaArchive Technical Documentation ## Project Overview -**InstaArchive** is a high-performance, React-based Progressive Web App (PWA) designed to browse and explore archived Instagram data with a native-feeling interface. It allows users to load their local Instagram archive directories (either official Instagram exports or Instaloader format) and browse posts, reels, and stories in a modern, responsive grid view. +**InstaArchive** is a high-performance, React-based Progressive Web App (PWA) designed to browse and explore archived Instagram data with a native-feeling interface. It allows users to load local archive directories (either official Instagram exports or Instaloader format) and browse posts, reels, and stories. -### Key Features +### Key Technical Features - **Local Archive Loading:** Uses the `webkitdirectory` API to scan and process local files securely on the client-side. - **Support for Multiple Formats:** Recognizes official Instagram export structures and Instaloader regex-based naming conventions. -- **Dynamic Media Grid:** Customizable grid layouts (1:1 and 3:4 aspect ratios) with adjustable offsets ("bumps") for aesthetic alignment. -- **Story Viewer:** Native-like story experience with progress bars, automated playback, and touch/click navigation. -- **Post Detail Modal:** Comprehensive view for posts with media carousels, captions, and seamless navigation between posts. -- **Video Support:** Automatic video thumbnail generation and playback. -- **PWA Ready:** Built with `vite-plugin-pwa` for offline capabilities and a standalone application experience. +- **Compressed Metadata**: Support for `.json.xz` file decompression using `xz-decompress` (WASM-powered). +- **Dynamic Media Grid**: Customizable grid layouts (1:1 and 3:4 aspect ratios) with adjustable offsets ("bumps") for aesthetic alignment. +- **Story Viewer**: Native-like story experience with segmented progress bars, automated playback, audio controls, and chronological sorting. +- **Auto-Unmute**: Videos default to unmuted when opened in full view for a better user experience. +- **PWA Ready**: Built with `vite-plugin-pwa` for offline capabilities and a standalone application experience. ### Main Technologies - **Frontend:** React 19, Vite, TypeScript @@ -19,39 +19,21 @@ - **Icons:** Lucide React - **Animations:** Framer Motion (`motion/react`) - **Utility:** Date-fns, clsx, tailwind-merge -- **PWA:** vite-plugin-pwa +- **Decompression**: xz-decompress (WASM) -*Note: While `better-sqlite3`, `express`, and `@google/genai` are listed in `package.json`, the current core application logic is entirely frontend-driven.* - -## Building and Running - -### Prerequisites -- Node.js (Latest LTS recommended) -- npm or yarn - -### Commands +## Commands - `npm install`: Install project dependencies. - `npm run dev`: Start the local development server on port 3000. - `npm run build`: Generate the production-ready build in the `dist` folder. - `npm run preview`: Locally preview the production build. - `npm run lint`: Execute TypeScript type-checking (`tsc --noEmit`). -- `npm run clean`: Remove the `dist` directory. - -### Environment Variables -- `GEMINI_API_KEY`: Required for AI-integrated features (though currently unutilized in core logic). -- `DISABLE_HMR`: If set to `true` (standard in AI Studio environments), Hot Module Replacement is disabled to prevent flickering during agent-driven edits. ## Development Conventions - -- **Component Architecture:** Functional components with modern hooks. All main application logic currently resides in `src/App.tsx`. -- **Styling Strategy:** Utility-first CSS using Tailwind CSS v4. Styles are largely co-located with components. -- **Type Safety:** Strict TypeScript usage for all components and utility functions. -- **Iconography:** Consistent use of `lucide-react` for all UI icons. -- **Animations:** Smooth transitions and gestures powered by `motion/react`. -- **File Handling:** Privacy-focused client-side scanning of archive directories using browser-native APIs. +- **Component Architecture:** Functional components with modern hooks. +- **State Management**: React `useState`, `useMemo`, and `useCallback` for optimized performance during large archive scans. +- **File Handling:** Privacy-focused client-side scanning of archive directories. - **Project Structure:** - - `src/App.tsx`: Main entry point and core application logic. + - `src/App.tsx`: Main entry point containing application logic and UI components. - `src/main.tsx`: React DOM mounting. - `src/index.css`: Global styles and Tailwind imports. - `vite.config.ts`: Project build and PWA configuration. - - `metadata.json`: Project description for external integration tools. diff --git a/README.md b/README.md index 548fb50..edb6081 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,43 @@ -
-GHBanner -
+# InstaArchive Viewer -# Run and deploy your AI Studio app +A high-performance React PWA for browsing archived Instagram data with a native-feeling interface. Supports both official Instagram exports and Instaloader archives. -This contains everything you need to run your app locally. +## Features -View your app in AI Studio: https://ai.studio/apps/29dc2807-7763-419f-9f2f-ac644e1bf4a1 +- **Local Privacy**: All processing is done client-side using browser APIs. Your data never leaves your computer. +- **Multiple Formats**: Supports official Instagram JSON exports and Instaloader regex-based naming conventions. +- **Metadata Support**: Robust parsing of `.json` and `.json.xz` files for captions, timestamps, and story metadata. +- **Story Viewer**: Native-like story experience with segmented progress bars, auto-playback, and audio controls. +- **Media Grid**: Customizable 1:1 or 3:4 grid views with adjustable offsets for aesthetic alignment. +- **Auto-Deduplication**: Intelligently prefers video files over thumbnail images for the same post. ## Run Locally -**Prerequisites:** Node.js +**Prerequisites:** Node.js (LTS recommended) +1. **Install dependencies:** + ```bash + npm install + ``` -1. Install dependencies: - `npm install` -2. Set the `GEMINI_API_KEY` in [.env.local](.env.local) to your Gemini API key -3. Run the app: - `npm run dev` +2. **Start the development server:** + ```bash + npm run dev + ``` + +3. **Open in browser:** + Navigate to `http://localhost:3000` and select your Instagram archive directory. + +## Building for Production + +To generate a production-ready build in the `dist` folder: + +```bash +npm run build +``` + +To preview the build: + +```bash +npm run preview +```