# Pulse Pantry Polished CDN-only React pantry planner for tracking ingredients, matching recipes, generating AI meal plans, and building smart shopping lists. ## Masterplan - Help home cooks reduce food waste by prioritizing pantry/fridge items that expire soon. - Serve mobile-first household cooks, meal preppers, and grocery planners who need quick “what should I cook?” guidance. - Provide an install-free prototype using realistic sample pantry, recipe, and shopping data. - Keep the app lightweight and runtime-safe: static HTML, CDN React, no JSX transform, no bundler, minimal state. - Include optional AI meal-planning via a hosted `/api/ai/completion` endpoint when available. ## Tech Stack & Architecture - **Runtime:** Static browser app booted from `index.html`. - **React:** `react@19.2.0` and `react-dom@19.2.0/client` loaded from `https://esm.sh`. - **Templating:** `htm@3.1.1` bound to `React.createElement` in `src/jsx.js`; all components use tagged templates, not JSX. - **Styling:** Tailwind CDN script in `index.html` plus custom CSS variables/utilities in `styles/main.css`. - **Routing:** Hash-based routing in `src/App.js`. - Valid pages: `#/pantry`, `#/recipes`, `#/list`. - Unknown or empty hash falls back to `pantry`. - **State management:** Local React state plus `AppContext`. - `src/mainProviders.js` stores `darkMode` and toggles `.dark` on ``. - `src/App.js` owns current page, hash navigation, pantry search, loading state, and AI form state. - **Data:** Static sample data from `src/data/pantry.js`. - **Backend:** No owned backend in this repo. The AI feature calls an external/platform-provided endpoint: - `POST /api/ai/completion` - Request body includes `prompt`, `appId: window.GENMB_APP_ID`, and `maxTokens`. - This endpoint must exist in the hosting environment; static local hosting without it will make AI generation fail gracefully. ### File Connection Flow `index.html` loads Tailwind CDN, `styles/main.css`, and the module entry `src/main.js`. `src/main.js` renders: ```js ``` `MainProviders` exposes theme context. `App` imports shared components and sample data, listens to `window.location.hash`, and renders the selected view. ## File Structure ```txt index.html # Static shell; loads Tailwind CDN, main.css, and src/main.js styles/main.css # HSL theme tokens, dark mode variables, shadows, safe-area helpers, skeleton shimmer src/main.js # ReactDOM entrypoint; mounts App inside MainProviders src/jsx.js # htm binding; required for all React components in this no-build app src/mainProviders.js # AppContext provider; manages darkMode and .dark class on src/App.js # Hash router; Pantry, Recipes, AI planner, shopping list, loading/empty states src/data/pantry.js # Static pantryItems, recipes, shoppingList seed data src/components/Header.js # Safe-area top bar, app title/subtitle, dark-mode toggle src/components/BottomNav.js # Fixed mobile-first nav for pantry/recipes/list src/components/PantryCard.js # Pantry item card with freshness label and clamped progress bar src/components/RecipeCard.js # Recipe match card with tags and pantry ingredient list CLAUDE.md # Project instructions/documentation target; keep in sync with this doc ``` ## Key Features ### Pantry Overview Implemented in `PantryView` inside `src/App.js`. Requirements: - Show a primary “Tonight’s signal” recommendation. - Compute urgent items from `daysLeft <= 3`. - Display stat cards: - tracked item count - use-soon count - recipe coverage, currently hardcoded as `86%` - Search pantry by item `name` or `category`. - Show skeleton cards while simulated loading is true. - Show `EmptyState` when search returns no results. - Render matching items with `src/components/PantryCard.js`. Pantry item model from `src/data/pantry.js`: ```js { id: 'p-001', name: 'Tuscan cannellini beans', category: 'Protein', quantity: '3 cans', daysLeft: 16, location: 'Lower pantry shelf', emoji: '🫘' } ``` ### Freshness Cards Implemented in `src/components/PantryCard.js`. Rules: - `daysLeft <= 3`: label `Use soon`, destructive/red styling. - `daysLeft <= 10`: label `Fresh`. - Otherwise: label `Shelf stable`. - Progress bar width is clamped to avoid invisible/overflow bars: ```js Math.max(8, Math.min(100, daysLeft * 3)) ``` Gotcha: - `daysLeft` is coerced with `Number(item?.daysLeft ?? 0)`. - Missing item fields have safe fallbacks; preserve this pattern for runtime safety. ### Recipe Matches Implemented with `RecipeCard` and the recipes view in `src/App.js`. Requirements: - Display static recipe cards from `recipes`. - Each recipe shows: - title - time - servings - match percentage - tags - up to four pantry ingredients - gradient accent Recipe model: ```js { id: 'r-001', title: 'Crispy White Bean Kale Skillet', time: '24 min', match: 92, servings: 3, tags: ['high protein', 'one pan'], ingredients: [ 'Tuscan cannellini beans', 'Lacinato kale', 'Sourdough boule', 'Roasted red peppers' ], accent: 'from-emerald-500/25 to-amber-400/25' } ``` ### AI Meal Planner Implemented as `AiMealPlanner` in `src/App.js`. Requirements: - Provides a default prompt: “Give me a quick dinner plan that uses my use-soon items first.” - Builds a pantry summary from current `pantryItems`. - Sends a concise meal-planning prompt to `POST /api/ai/completion`. - Uses `window.GENMB_APP_ID` as `appId`. - Handles: - blank prompt validation - loading state - success message - generic request failure - `429` rate limit with user-friendly message - Expected response shape is a JSON object containing generated text. When changing this code, inspect the existing response parsing in `src/App.js` and preserve current fallback behavior. External integration: ```http POST /api/ai/completion Content-Type: application/json { "prompt": "You are Pulse Pantry's practical meal-planning assistant...", "appId": window.GENMB_APP_ID, "maxTokens": 500 } ``` Gotcha: - This API is not implemented in this repository. It depends on the hosting/runtime platform. Do not add server assumptions unless intentionally converting the app away from CDN-only static mode. ### Smart Shopping List Implemented in `src/App.js` using `shoppingList` from `src/data/pantry.js`. Requirements: - Show grocery items grouped visually by `section` and `priority`. - Priorities in sample data are `today` and `this week`. - Keep the list read-only unless adding local state persistence intentionally. Shopping item model: ```js { id: 's-001', name: 'Fresh dill', section: 'Produce', priority: 'today' } ``` ### Navigation and Theme - `Header` logo button always navigates to `pantry`. - `BottomNav` controls the three valid hash routes. - Dark mode is in-memory only; it does not persist to `localStorage`. - Bottom navigation is fixed and mobile-first; main page content must leave enough bottom padding so it is not hidden. ## Design Guidelines - **Visual direction:** warm, modern pantry/planner UI; soft cards, rounded corners, food-focused emoji accents. - **Color system:** all colors are CSS variables in `styles/main.css` using HSL triplets: - light background: warm cream `--background: 42 45% 96%` - foreground: deep green `--foreground: 154 32% 12%` - primary: pantry green - secondary: warm amber - destructive: tomato red - **Dark mode:** `.dark` overrides the same CSS variables; components should continue to reference variables instead of hardcoded light/dark colors. - **Typography:** system sans stack with Inter preferred if available; heavy weights (`font-black`, `font-extrabold`) for headings and badges. - **Shape:** use CSS radius tokens: - `--radius-md` for icons/small containers - `--radius-lg` for cards, inputs, nav buttons - **Motion:** use `.smooth` for transitions. Respect reduced motion via existing media query. - **Mobile behavior:** - Header uses `.safe-top`. - Bottom nav uses `.safe-bottom`. - Touch targets should be at least `44px`; current nav/input targets are larger. - Layouts start single-column and expand with Tailwind `sm:`/`lg:` grids. ## App Flow 1. User opens `index.html`. 2. `src/main.js` mounts `App` inside `MainProviders`. 3. `App` reads the hash: - empty or invalid hash → pantry view - `#/pantry` → pantry overview - `#/recipes` → recipe matches and AI meal planner - `#/list` → shopping list 4. User can: - search pantry items by name/category - inspect freshness and urgency - switch to recipes - request an AI meal plan, if `/api/ai/completion` is available - switch to shopping list - toggle dark mode Edge cases: - Invalid hashes must not crash; they resolve to `pantry`. - Missing/undefined data should not crash cards; existing components use optional chaining and fallbacks. - Search with no matches renders `EmptyState`. - AI endpoint failure should leave the app usable and show an error. - Static hosting without an API endpoint is acceptable; only AI generation is affected. ## Conventions - **No JSX.** Use `htm` templates imported as: ```js import { html } from './jsx.js'; ``` or from components: ```js import { html } from '../jsx.js'; ``` - **Component syntax:** use htm component interpolation: ```js html`<${PantryCard} item=${item} />` ``` not ``. - **React imports:** import React directly from esm.sh when hooks/context are needed: ```js import React from 'https://esm.sh/react@19.2.0'; ``` - **Keys:** add `key=${item.id}` or equivalent inside mapped htm elements/components. - **Styling:** prefer Tailwind utility classes referencing CSS variables: - `bg-[hsl(var(--card))]` - `text-[hsl(var(--foreground))]` - `border-[hsl(var(--border))]` - **Do not hardcode duplicate color palettes** in components. Update `styles/main.css` tokens instead. - **Data changes:** edit `src/data/pantry.js`; keep IDs stable and unique (`p-*`, `r-*`, `s-*`). - **Adding a new page:** 1. Add page id to `validPages` in `src/App.js`. 2. Add a nav item in `src/components/BottomNav.js` if it should be user-accessible. 3. Update `Header` title logic in `src/components/Header.js`. 4. Add render branch in `App`. 5. Ensure unknown hashes still fall back to pantry. - **Adding reusable UI:** create a component under `src/components/`, import `html`, use safe fallbacks for props, and keep it stateless unless there is a clear local interaction. - **Persistence:** currently none. If adding persistence, prefer `localStorage` for this static prototype before introducing a backend. - **Backend/API changes:** do not imply Next.js, Prisma, auth, or server routes unless the project is intentionally migrated. Current architecture is CDN-only static React. ## Platform (GenMB) This app is built and hosted on GenMB. **Runtime:** Browser sandbox (iframe) or Cloud Run. No Node.js server — all code runs client-side unless `backend/` exists. **Dependencies:** CDN-only (esm.sh, cdn.tailwindcss.com, unpkg). Use ES module imports with full CDN URLs. No `npm install` at runtime. **Entry point:** `index.html` must include all CDN script tags. Tailwind via CDN with inline config. **Built-in services (relative API paths only, never hardcode domains):** - `/api/ai/completion` — AI proxy | `/api/data/{appId}/*` — PostgreSQL (DataConnect SDK) - `/api/storage/{appId}/*` — File uploads (GCS) | `/api/auth/google/*` — Google OAuth - `/api/contact/submit` — Contact form | SDKs: `window.genmb.db`, `.storage`, `.auth` **File structure:** `index.html` (entry), `src/` (source), `styles/` (CSS), `backend/` (optional FastAPI), `CLAUDE.md` (this file). **Cannot:** Install npm packages at runtime, access filesystem, make direct server-side calls from frontend, modify infra.