JustMeme: The Spatial Intelligence Engine

"Pictures are worth a thousand words... so we built an engine to compress them."

JustMeme is a semantic compression engine that translates user intent into visual culture using Spatial Reasoning and Google Gemini 3.0. It solves the "Blind AI" problem by burning a diagnostic grid into images before the model sees them, allowing for pixel-perfect text placement and humor deconstruction.

🏗️ Architecture

The application is built on a three-tier architecture designed for low-latency visual reasoning and high-fidelity rendering.

graph LR
    subgraph Client ["🖥️ CLIENT LAYER (React + Vite)"]
        UI[User Interface <br/> App.tsx]
        VGE[Visual Grounding Engine <br/> gridUtils.ts]
        CR[Canvas Renderer]
        SF[Sonic Feedback <br/> soundUtils.ts]
        
        UI --> VGE
        VGE --> CR
        UI -.-> SF
    end

    subgraph Service ["⚙️ SERVICE LAYER"]
        GA[Gemini Adapter <br/> geminiService.ts]
        PI[Prompt Injector <br/> System Persona Logic]
        
        GA --> PI
    end

    subgraph Cloud ["☁️ AI INFRASTRUCTURE (Google)"]
        G3F[Gemini 3.0 Flash <br/> Reasoning Core]
        G25F[Gemini 2.5 Flash <br/> Creative Vision Core]
        G25FL[Gemini 2.5 Flash Lite <br/> Concept Core]
    end

    Client --> Service
    Service --> Cloud

    PI --> G3F
    PI --> G25F
    PI --> G25FL

Loading

1. Client Layer (React + Vite)

The frontend is a specialized WYSIWYG editor optimized for memetic interactions.

• User Interface (App.tsx): Handles Image Upload, Vibe Selector, and Intent Input.
• Visual Grounding Engine (gridUtils.ts): The core innovation. It uses the Canvas API to inject a 10x10 Diagnostic Grid, Rotation Guides (15°/30°), and Scale Anchors directly into the image pixel data before AI processing.
• Canvas Renderer: A high-performance graphic generation engine handling Coordinate Mapping, Text Wrapping, and Stroke Rendering.
• Sonic Feedback (soundUtils.ts): Uses the Web Audio API (Oscillator Synthesis) to provide haptic-like audio cues for a "cyberpunk" user experience.

2. Service Layer

Orchestrates the communication between the client's visual data and the AI models.

• Gemini Adapter (geminiService.ts): Handles Model Routing, Error Handling, and rigorous JSON Parsing to ensure the AI output matches the strict schema required by the renderer.
• Prompt Injector: Manages System Persona Logic, dynamically injecting "Vibes" (e.g., "Classic", "Gen Z" (Chaos), "Dark" (Nihilism)) into the context window.

3. AI Infrastructure (Google)

We utilize a multi-model approach to balance intelligence, creativity, and speed.

• 🟣 Gemini 3.0 Flash (Reasoning Core)
  • Role: The Meme Architect.
  • Specs: Thinking Budget: 1024 tokens.
  • Tasks: Spatial Analysis, Humor Deconstruction, JSON Layout Generation.
• 🟣 Gemini 2.5 Flash (Creative Vision Core)
  • Role: The Artist.
  • Tasks: Style Transfer, "Reimagine" Feature (e.g., "Make it 8-bit"), Complex Visual Transformations.
• 🟣 Gemini 2.5 Flash Lite (Concept Core)
  • Role: The Ideator.
  • Tasks: Rapid Idea Generation, Random Prompt Synthesis.

📂 Project Structure

Core & Configuration

• App.tsx: The main controller component. Manages application state (intent, generation, editing), orchestrates the UI, and handles drag-and-drop events.
• index.html: The entry point. Contains Tailwind configuration, custom font imports (Rajdhani, Koulen, Impact), and global CSS for the "Cyberpunk/Terminal" aesthetic.
• types.ts: TypeScript definitions. Defines the schema for MemeData, LayoutElement, and the GenerationResponse expected from Gemini.
• vite.config.ts: Vite build configuration, including environment variable handling for the API key.

Components (UI)

• components/InteractiveCanvas.tsx: The WYSIWYG editor. Renders the meme, overlays the editable text/sticker layers, handles mouse/touch interactions for dragging, resizing, and rotating.
• components/StudioControls.tsx: The bottom control bar. Contains the prompt input, "Vibe" selector, "Execute" button, and the animated "Architect" mascot.
• components/SidebarLeft.tsx: The navigation sidebar. Displays the Meme Library (Blueprints), Prompt History, and Example Ideas.
• components/GlobalToolsPanel.tsx: The right-hand panel (or bottom drawer on mobile). Manages the Layer Stack, verified Google Search sources, and the "Nano Banana" Remix tools.
• components/InspectorPanel.tsx: Contextual editor. appears when an element is selected. Allows fine-tuning of font family, colors, stroke, skew, and spatial bounds.
• components/LoadingOverlay.tsx: The aesthetic loading screen. Displays "hacking" animations and humorous status messages while the AI generates content.

Services (Logic)

• services/geminiService.ts: The AI Brain. Connects to the Google GenAI SDK. Constructs the "System Prompt", manages the Thinking Budget, handles tool calls (Google Search), and parses JSON responses.
• services/grid/overlayPainter.ts: The "Vision" Engine. Draws the cyan coordinate grid and purple angular guides onto images before sending them to the LLM.
• services/grid/memeEngine.ts: The "Render" Engine. Takes the abstract JSON layout and draws the final high-resolution image using HTML5 Canvas (handling text wrapping, stroke outlines, and skew transformations).
• services/grid/imageUtils.ts: Utilities for handling Base64 strings, fetching blobs, and stitching multiple user uploads into a single collage.
• services/soundUtils.ts: The Audio Engine. Uses the Web Audio API to synthesize beeps, clicks, and data-stream sounds for user feedback without external assets.
• services/logger.ts: Debugging utility. Formats AI prompts and responses in the browser console for easier inspection.

Data

• data/prebaked.ts: A registry of static, pre-generated memes used for instant demos and fallback scenarios.
• data/prebaked/*.ts: Individual meme definition files (e.g., technicalDebt.ts, vibeCodingQuota.ts) containing the JSON structure for specific classic memes.

🚀 Key Features

Feature	Tech Component	Description
Visual Grounding	overlayPainter.ts	Burns a coordinate grid into images to fix LLM spatial blindness.
Reasoning Trace	gemini-3-flash	Uses a Thinking Budget to plan humor and layout before generating JSON.
Style Transfer	gemini-2.5-flash	Reimagines existing memes into new art styles (Pixel Art, Claymation, etc.).
Idea Generator	gemini-2.5-flash-lite	Generates random, culturally relevant meme concepts on the fly.
Sonic Feedback	soundUtils.ts	Generates synth sounds for interactions without external assets.

📦 Tech Stack

• Frontend: React 18, TypeScript, Vite, TailwindCSS
• AI Models: Google Gemini API (@google/genai SDK)
• Graphics: HTML5 Canvas API
• Audio: Web Audio API

🛠 Getting Started

# Install dependencies
npm install

# Run the development server
npm run dev

---

Built with ❤️ and ☕. JustMeme is alive.