Readme updated

README.md

@@ -1,43 +1,478 @@
 ---
 title: Powerpoint AI
-emoji: 🎨
+emoji: "🎨"
 colorFrom: green
 colorTo: yellow
 sdk: docker
 app_port: 7860
-pinned: false
+pinned: true
 ---
 
-# PowerPoint AI Generator
+# Powerpoint AI
 
-AI-powered presentation generator with a Google Slides-like editor. Create professional presentations using Llama-3.3-70B-Instruct via HuggingFace Inference, with automatic Unsplash image integration and Neo-Brutalism template support.
+Powerpoint AI is a Next.js presentation generator that turns a prompt into editable slides, lets the user refine them in a Google Slides-like editor, and exports the final deck as a `.pptx` file. The project is built around Hugging Face login and inference, a template-driven slide system, and a hybrid editor that supports both generated slide specs and draggable canvas elements.
 
-## Features
+This README is written as a learning guide. It explains:
 
-- **AI Slide Generation** using Llama-3.3-70B-Instruct (HF Inference)
-- **Template System** with Neo-Brutalism theme (dot grids, thick borders, hard shadows, bright colors)
-- **Unsplash Integration** for automatic slide images
-- **Google Slides-like Editor** with drag-and-drop, inline text editing
-- **Multiple Slide Types**: Title, Bullets, Content-Image, Quote, Comparison, Chart, Stats, Section
-- **Export to PowerPoint** (.pptx)
-- **HuggingFace OAuth** login
+1. What the app does end-to-end.
+2. How to run it locally and deploy it to a Hugging Face Space.
+3. How the request flow moves from the homepage to the editor.
+4. What each important file does and how the files connect.
+5. How to rebuild the project manually if you want to learn by coding it yourself.
 
-## Tech Stack
+## What The App Does
 
-- Next.js 15 (App Router, Standalone output)
-- TypeScript, TailwindCSS v4
-- HuggingFace Inference Client
-- pptxgenjs for export
-- Radix UI primitives
+At a high level, the app works like this:
+
+1. The user opens `/` and enters a presentation prompt.
+2. The home page verifies that the user is logged in with Hugging Face.
+3. The prompt and selected template are stored in browser session/local storage.
+4. The app routes the user to `/editor`.
+5. The editor calls `/api/presentations/generate` with the prompt and model.
+6. The backend requests structured JSON slides from Hugging Face Inference.
+7. The response is normalized into the app's `SlideSpec` shape.
+8. The editor renders those slides through the template/theme system.
+9. The user edits text, layout, images, and formatting inside the editor.
+10. The user exports the deck as an editable PowerPoint file.
+
+## Stack
+
+- Next.js App Router
+- React + TypeScript
+- Tailwind CSS
+- Hugging Face OAuth + Inference
+- Unsplash image search/download integration
+- `pptxgenjs` for editable PPTX export
+
+## Prerequisites
+
+You need:
+
+- Node.js 20+
+- npm
+- A Hugging Face account
+- A manual Hugging Face connected OAuth app
+- Optional: an Unsplash access key if you want real image search results
 
 ## Environment Variables
 
-Set these as **Secrets** in your HuggingFace Space settings:
+Set these in `.env` for local development or in Hugging Face Space secrets/variables for deployment.
+
+| Variable | Required | Purpose |
+| --- | --- | --- |
+| `HUGGINGFACE_CLIENT_ID` | Yes for login | Client ID from your manual Hugging Face connected app |
+| `HF_TOKEN` | Optional | Fallback Hugging Face token if the user is not logged in |
+| `HF_API_KEY` | Optional | Alternate fallback token name supported by the generation route |
+| `UNSPLASH_ACCESS_KEY` | Optional | Enables live Unsplash image search/results |
+| `NEXT_PUBLIC_UNSPLASH_ACCESS_KEY` | Optional | Alternate client-visible Unsplash key fallback used by some routes |
+
+Notes:
+
+- This project is currently set up for a **manual connected app**, not Hugging Face Spaces native OAuth.
+- Do **not** add `hf_oauth: true` if you want to keep using your existing connected app.
+- The allowed redirect URI in your Hugging Face connected app should be your actual app origin, for example:
+  - `http://localhost:3000/`
+  - `https://reubencf-powerpoint-ai.hf.space/`
+
+## Local Development
+
+1. Install dependencies:
+
+   ```bash
+   npm install
+   ```
+
+2. Create `.env` and add the variables you need:
+
+   ```env
+   HUGGINGFACE_CLIENT_ID=your_client_id
+   HF_TOKEN=your_optional_fallback_token
+   UNSPLASH_ACCESS_KEY=your_optional_unsplash_key
+   ```
+
+3. Start the dev server:
+
+   ```bash
+   npm run dev
+   ```
+
+4. Open:
+
+   ```text
+   http://localhost:3000
+   ```
+
+5. Log in with Hugging Face, enter a prompt, and verify that generation reaches `/editor`.
+
+## Hugging Face Space Deployment
+
+This repo is configured as a Docker Space using the frontmatter at the top of this file.
+
+To deploy:
+
+1. Create a Hugging Face Docker Space.
+2. Push this repo to the Space.
+3. Add the required Space secrets/variables:
+   - `HUGGINGFACE_CLIENT_ID`
+   - optionally `HF_TOKEN`
+   - optionally `UNSPLASH_ACCESS_KEY`
+4. In your manual connected Hugging Face app settings, add the Space origin as an allowed redirect URI.
+5. Redeploy the Space.
+
+Important:
+
+- The app currently uses `HUGGINGFACE_CLIENT_ID` through `/api/auth/client-id`.
+- The login flow dynamically uses `window.location.origin` as the redirect target.
+- On Hugging Face Spaces, the homepage detects iframe/Space hosting and escapes the container before login if needed.
+
+## End-To-End Architecture Flow
+
+### 1. Route entrypoints
+
+- `/` loads the homepage prompt builder.
+- `/editor` loads the editor only if a generation session was created from the homepage.
+- `/template` exists as a template preview/browsing route.
+- `/api/*` provides auth, generation, AI edit, image search, and image proxy services.
+
+### 2. Homepage to editor handoff
+
+The homepage stores these keys before routing to the editor:
+
+- `generationPrompt`
+- `generationModel`
+- `isGenerating`
+- `editorAccess`
+- `ppt_theme` in local storage
+
+The editor reads those values on mount to decide whether to:
+
+- redirect back to `/`
+- restore the chosen theme
+- call the generation API automatically
+
+### 3. Generation backend flow
+
+`/api/presentations/generate` does the following:
+
+1. Validates the prompt.
+2. Resolves the Hugging Face token from headers, cookies, or env fallback.
+3. Builds the system prompt with `lib/slide-prompt.ts`.
+4. Calls the approved model through `lib/hf-client.ts`.
+5. Parses loose model JSON defensively.
+6. Normalizes the payload into the app's slide shape.
+7. Optionally enriches image slides with Unsplash data.
+8. Returns normalized slide data for the editor.
+
+### 4. Editor rendering flow
+
+The editor supports two rendering modes:
+
+- **Template mode**: uses `SlideSpec` and `SlideFactory` to render theme-specific layouts.
+- **Canvas mode**: uses positioned `EditorElement` objects for draggable/editable items.
+
+For generated presentations, the app first normalizes API data into `SlideSpec`, then builds canvas/editor elements where needed so the legacy editing features still work.
+
+### 5. Export flow
+
+- The top bar export button calls `hooks/useExport.ts`.
+- `useExport` delegates to `lib/editable-pptx-export.ts`.
+- The exporter converts the current editor state into an editable `.pptx`.
+
+## How The Editor Works Internally
+
+The editor is intentionally state-heavy because it coordinates:
+
+- the list of slides
+- the current slide index
+- selected element state
+- inline text editing state
+- zoom state
+- undo/redo history
+- AI text editing
+- image replacement/search
+- template-rendered slides and older element-based slides
+
+The two most important ideas are:
+
+1. `SlideSpec` is the declarative template-friendly shape.
+2. `SlideModel` / `EditorElement` is the interactive editor canvas shape.
+
+That split is why some code looks duplicated: the app preserves a template rendering pipeline while also keeping direct canvas editing features.
+
+## How Templates And Themes Are Organized
+
+There are three template families right now:
+
+- `neobrutalism`
+- `galeryn`
+- `noisy`
+
+Each template has:
+
+- a declarative definition in `data/templates/*.ts`
+- theme-specific React layouts in `components/slides/<theme>/layouts.tsx`
+- fallback generic layout components in `components/slides/*.tsx`
+
+The registry in `data/templates/index.ts` describes:
+
+- template IDs
+- layout IDs
+- field definitions
+- style tokens
+- default slide data
+
+The `SlideFactory` uses that registry plus the selected template ID to render the correct slide component.
+
+## How AI Text Editing, Image Search, And Export Connect
+
+### AI text editing
+
+- The editor opens `components/editor/AIToolsDialog.tsx`.
+- That dialog talks to `/api/ai-edit-text/route.ts`.
+- The route uses the Hugging Face provider layer to rewrite selected text.
+
+### Image search
+
+- The editor opens `components/UnsplashImageSearch.tsx`.
+- That component calls `/api/search-images/route.ts`.
+- `/api/unsplash-download/route.ts` is used for download attribution.
+- `/api/image-proxy/route.ts` helps keep remote images safe for capture/export flows.
+
+### Export
+
+- The editor export button calls `hooks/useExport.ts`.
+- `useExport` calls `lib/editable-pptx-export.ts`.
+- The export library reads current slides, theme data, and layout information to create a real PowerPoint file.
+
+## File Map
+
+This section is intentionally explicit so a new contributor can jump from route to component to helper without guessing.
+
+### App routes and app shell
+
+- `app/layout.tsx`
+  - Root HTML/layout wrapper.
+  - Adds global fonts, metadata, and the `ThemeProvider`.
+- `app/globals.css`
+  - Global styles and utility-level CSS used across pages/components.
+- `app/page.tsx`
+  - Root route entrypoint.
+  - Re-exports `components/home/HomePage.tsx`.
+- `app/editor/page.tsx`
+  - Guards `/editor` with `sessionStorage.editorAccess`.
+  - Renders `GoogleSlidesEditor`.
+- `app/template/page.tsx`
+  - Template preview/browsing route.
+
+### API routes
+
+- `app/api/presentations/generate/route.ts`
+  - Main slide generation endpoint.
+  - Calls `HFClient`, `buildSlidePrompt`, and Unsplash helpers.
+- `app/api/ai-edit-text/route.ts`
+  - AI text rewriting endpoint for the editor.
+- `app/api/search-images/route.ts`
+  - Searches Unsplash images for the editor modal.
+- `app/api/unsplash-download/route.ts`
+  - Handles Unsplash download tracking.
+- `app/api/image-proxy/route.ts`
+  - Proxies remote images for safe browser capture/export use.
+- `app/api/auth/client-id/route.ts`
+  - Returns `HUGGINGFACE_CLIENT_ID` to the client login flow.
+
+### Homepage and top-level UI
+
+- `components/home/HomePage.tsx`
+  - Landing page.
+  - Restores auth, handles login, stores generation state, and routes to `/editor`.
+- `components/ThemeProvider.tsx`
+  - Theme context wrapper built on `next-themes`.
+- `components/UnsplashImageSearch.tsx`
+  - Search/select modal for remote images.
+
+### Editor components
+
+- `components/editor/GoogleSlidesEditor.tsx`
+  - Main workspace.
+  - Owns generation bootstrap, editor state, slide switching, toolbar wiring, and export entry.
+- `components/editor/BottomToolbar.tsx`
+  - Floating toolbar for layout, typography, AI tools, zoom, and slide actions.
+- `components/editor/AIToolsDialog.tsx`
+  - Text-editing dialog for AI-powered text changes.
+
+### Slide rendering
+
+- `components/slides/SlideFactory.tsx`
+  - Central dispatcher that chooses the correct themed or fallback slide layout.
+- `components/slides/TitleSlideLayout.tsx`
+  - Generic fallback layout for title/subtitle slides.
+- `components/slides/AgendaSlideLayout.tsx`
+  - Generic fallback layout for agenda slides.
+- `components/slides/TitleAndBodyLayout.tsx`
+  - Generic fallback layout for title/body slides.
+- `components/slides/ThreeColumnLayout.tsx`
+  - Generic fallback layout for three-column slides.
+- `components/slides/ImageAndTextLayout.tsx`
+  - Generic fallback layout for image/text slides.
+- `components/slides/ReferenceLayout.tsx`
+  - Generic fallback layout for reference/list slides.
+- `components/slides/ThankYouLayout.tsx`
+  - Generic fallback layout for ending slides.
+- `components/slides/neobrutalism/layouts.tsx`
+  - Theme-specific layouts for the Neo-Brutalism template.
+- `components/slides/galeryn/layouts.tsx`
+  - Theme-specific layouts for the Galeryn template.
+- `components/slides/noisy/layouts.tsx`
+  - Theme-specific layouts for the Noisy template.
+- `components/slides/shared/PersistedDraggableSurface.tsx`
+  - Shared editable/draggable slide-surface logic used by themed layouts.
+
+### Template registry
+
+- `data/templates/index.ts`
+  - Template registry and template-related type definitions.
+- `data/templates/neo-brutalism.ts`
+  - Neo-Brutalism template declaration.
+- `data/templates/galeryn.ts`
+  - Galeryn template declaration.
+- `data/templates/noisy.ts`
+  - Noisy template declaration.
+
+### Hooks
+
+- `hooks/useExport.ts`
+  - Small export wrapper used by the editor.
+- `hooks/useKeyboardShortcuts.ts`
+  - Keyboard shortcut behavior for editor actions.
+- `hooks/useSlideHistory.ts`
+  - Undo/redo history storage for slides.
+
+### Library helpers
+
+- `lib/ai-models.ts`
+  - Approved model constants and model validation.
+- `lib/hf-client.ts`
+  - Hugging Face inference wrapper and provider-specific error handling.
+- `lib/slide-prompt.ts`
+  - System prompt builder and layout normalization helpers.
+- `lib/generated-presentation.ts`
+  - Typed generated-slide response helpers and `SlideSpec` mapping.
+- `lib/template-options.ts`
+  - Template picker labels and normalization of saved IDs.
+- `lib/theme-system.ts`
+  - Theme-level types/helpers used by the rendering system.
+- `lib/editor-types.ts`
+  - Shared editor model types.
+- `lib/editor-themes.ts`
+  - Theme/color/font definitions used by the editor and export code.
+- `lib/layout-templates.ts`
+  - Default canvas layout creation helpers.
+- `lib/editable-pptx-export.ts`
+  - Editable PowerPoint export implementation.
+- `lib/capture-element.ts`
+  - DOM capture helper used by image/export flows.
+- `lib/utils.ts`
+  - Small shared utility helpers.
+
+### Shared types
+
+- `types/index.ts`
+  - Project-wide shared types that do not belong to a single feature module.
+
+### Config
+
+- `next.config.ts`
+  - Next.js configuration.
+- `package.json`
+  - Scripts, dependencies, and project metadata.
+- `Dockerfile`
+  - Runtime image used by the Hugging Face Docker Space.
+
+## How To Manually Build This Project Yourself
+
+If you want to learn by recreating the app manually, build it in this order:
+
+### Step 1: Create the app shell
+
+1. Start a Next.js app with TypeScript and App Router.
+2. Add `app/layout.tsx` and `app/globals.css`.
+3. Add a `ThemeProvider` so dark/light mode is available globally.
+
+### Step 2: Build the homepage
+
+1. Create a landing page with:
+   - a prompt textarea
+   - a template picker
+   - a submit button
+2. Add client-side storage for:
+   - the prompt
+   - the selected template
+   - a session flag that allows `/editor`
+3. Add Hugging Face login/logout state restoration.
+
+### Step 3: Add Hugging Face login
+
+1. Create a manual connected app in Hugging Face settings.
+2. Add `HUGGINGFACE_CLIENT_ID` to env/secrets.
+3. Create `/api/auth/client-id/route.ts`.
+4. Use `oauthLoginUrl` and `oauthHandleRedirectIfPresent` on the homepage.
+5. Store the returned access token in local storage for later API calls.
+
+### Step 4: Create the generation API
+
+1. Create `/api/presentations/generate/route.ts`.
+2. Accept a prompt and optional model input.
+3. Resolve the Hugging Face token from headers/cookies/env.
+4. Build a strict system prompt that asks for presentation JSON.
+5. Call the model through a small Hugging Face client wrapper.
+6. Parse and normalize the model response into your own slide format.
+
+### Step 5: Define the slide data model
+
+1. Create a template-side shape like `SlideSpec`.
+2. Create an editor-side shape like `SlideModel` / `EditorElement`.
+3. Add normalization helpers that map generated API data into those shapes.
+
+### Step 6: Build the template system
+
+1. Define templates in `data/templates/*.ts`.
+2. Add a registry in `data/templates/index.ts`.
+3. Create a `SlideFactory` that renders a slide by template ID + layout ID.
+4. Add generic fallback layouts so rendering still works if a template-specific layout is missing.
+
+### Step 7: Build the editor
+
+1. Create an editor page that reads the generation session.
+2. Call the generation API on first load.
+3. Store slides, current selection, zoom, and undo/redo history.
+4. Render:
+   - a slide thumbnail rail
+   - a main canvas
+   - a toolbar
+   - dialogs/modals for AI editing and image search
+
+### Step 8: Add AI text editing and images
+
+1. Create `/api/ai-edit-text/route.ts`.
+2. Add a dialog to send selected text for rewrite.
+3. Create Unsplash search and download routes.
+4. Add an image picker modal in the editor.
+
+### Step 9: Add export
+
+1. Create a hook for export actions.
+2. Convert the current slide state into `pptxgenjs` calls.
+3. Expose a top-bar export button in the editor.
+
+### Step 10: Polish and verify
+
+1. Add keyboard shortcuts and history.
+2. Add route guards so `/editor` is only reached through the expected flow.
+3. Verify login, generation, editing, image selection, and export.
+
+## Contributor Notes
 
-| Variable | Required | Description |
-|---|---|---|
-| `UNSPLASH_ACCESS_KEY` | Optional | Unsplash API key for slide images |
-| `HF_TOKEN` | Optional | HuggingFace API token (fallback if OAuth not used) |
-| `HUGGINGFACE_CLIENT_ID` | Optional | HF OAuth client ID |
-| `HUGGINGFACE_CLIENT_SECRET` | Optional | HF OAuth client secret |
-| `NEXT_PUBLIC_HUGGINGFACE_CLIENT_ID` | Optional | Public HF OAuth client ID |
+- Prefer the template registry and `SlideSpec` path when adding new slide styles.
+- Keep behavior changes separate from cleanup/documentation changes.
+- If you change storage keys or generation payload shapes, update both the homepage/editor handoff and this README.
+- If you add a new route or editor subsystem, add it to the file map above so new contributors can follow the flow quickly.

app/api/auth/client-id/route.ts

@@ -1,3 +1,10 @@
+/*
+ * route.ts
+ * Purpose: Returns the configured Hugging Face OAuth client ID to the browser login flow.
+ * Used by: components/home/HomePage sign-in flow.
+ * Depends on: Space/app environment variables and NextResponse.
+ */
+
 import { NextResponse } from 'next/server';
 
 export async function GET() {

app/api/image-proxy/route.ts

@@ -1,3 +1,10 @@
+/*
+ * route.ts
+ * Purpose: Fetches remote images through a same-origin route so export/canvas code can safely reuse them.
+ * Used by: Image capture/export helpers and any UI path that needs proxied remote images.
+ * Depends on: Next.js route handlers and remote fetch.
+ */
+
 import { NextRequest, NextResponse } from 'next/server';
 
 export async function GET(request: NextRequest) {

app/api/presentations/generate/route.ts

@@ -1,3 +1,11 @@
+/*
+ * route.ts
+ * Purpose: Turns a presentation prompt into normalized slide JSON and enriches
+ * image slides with Unsplash results before the editor receives the payload.
+ * Used by: GoogleSlidesEditor when a new prompt is submitted from the home page.
+ * Depends on: HFClient, prompt-building helpers, model allow-listing, and optional Unsplash access.
+ */
+
 import { NextRequest, NextResponse } from 'next/server';
 import { HFClient, HFGenerationError } from '@/lib/hf-client';
 import { LLAMA_PRESENTATION_MODEL, isAllowedPresentationModel } from '@/lib/ai-models';
@@ -27,6 +35,7 @@ class PresentationGenerationError extends Error {
   }
 }
 
+// These helpers normalize loosely structured model output into predictable editor data.
 function toStringArray(value: unknown): string[] {
   if (Array.isArray(value)) {
     return value
@@ -144,6 +153,7 @@ function getProviderFailureMessage(error: unknown): string {
   return 'Slide generation failed.';
 }
 
+// Retry once for transient provider failures so short upstream hiccups do not surface immediately to users.
 async function fetchModelResponse(hf: HFClient, prompt: string): Promise<string> {
   try {
     return await hf.generateSlideContent(prompt, LLAMA_PRESENTATION_MODEL);
@@ -174,6 +184,7 @@ async function fetchModelResponse(hf: HFClient, prompt: string): Promise<string>
   }
 }
 
+// The model sometimes wraps JSON in markdown or returns an array directly, so parsing is intentionally defensive.
 function parseGeneratedPayload(response: string): { presentationName?: string; slides: unknown[] } {
   const cleanedJson = response
     .trim()
@@ -248,6 +259,7 @@ function parseGeneratedPayload(response: string): { presentationName?: string; s
   };
 }
 
+// The editor expects a stable layout/content shape regardless of how the model phrased the response.
 function normalizeSlides(slides: unknown[]): Slide[] {
   const total = slides.length;
 
@@ -306,8 +318,38 @@ async function fetchImageForSlide(query: string): Promise<string | undefined> {
   }
 }
 
+function resolveHuggingFaceToken(req: NextRequest) {
+  const headerToken = req.headers.get('x-hf-token');
+  if (headerToken) return headerToken;
+
+  const cookieToken = req.cookies.get('hf_api_key')?.value;
+  if (cookieToken) return cookieToken;
+
+  const authHeader = req.headers.get('authorization');
+  if (authHeader?.startsWith('Bearer ')) {
+    return authHeader.slice(7);
+  }
+
+  return process.env.HF_TOKEN || process.env.HF_API_KEY || null;
+}
+
+function buildPresentationName(prompt: string) {
+  return prompt.length > 50 ? `${prompt.substring(0, 47)}...` : prompt;
+}
+
+async function attachImagesToSlides(slides: Slide[]) {
+  return Promise.all(
+    slides.map(async (slide) => {
+      if (slide.layout !== 'image_and_text' || !slide.imageKeyword) return slide;
+      const imageUrl = await fetchImageForSlide(slide.imageKeyword);
+      return { ...slide, imageUrl };
+    })
+  );
+}
+
 export async function POST(req: NextRequest) {
   try {
+    // The request shape is intentionally small because generation state is coordinated client-side.
     const body = await req.json();
     const prompt = typeof body.prompt === 'string' ? body.prompt.trim() : '';
     const model = body.model;
@@ -323,13 +365,7 @@ export async function POST(req: NextRequest) {
       console.warn(`Ignoring unsupported presentation model "${model}" and forcing ${LLAMA_PRESENTATION_MODEL}.`);
     }
 
-    let hfToken = req.headers.get('x-hf-token');
-    if (!hfToken) hfToken = req.cookies.get('hf_api_key')?.value || null;
-    if (!hfToken) {
-      const authHeader = req.headers.get('authorization');
-      if (authHeader?.startsWith('Bearer ')) hfToken = authHeader.slice(7);
-    }
-    if (!hfToken) hfToken = process.env.HF_TOKEN || process.env.HF_API_KEY || null;
+    const hfToken = resolveHuggingFaceToken(req);
 
     if (!hfToken) {
       return NextResponse.json(
@@ -342,7 +378,7 @@ export async function POST(req: NextRequest) {
     }
 
     const systemPrompt = buildSlidePrompt(prompt);
-    const presentationName = prompt.length > 50 ? `${prompt.substring(0, 47)}...` : prompt;
+    const presentationName = buildPresentationName(prompt);
     const hf = new HFClient({ apiKey: hfToken, model: LLAMA_PRESENTATION_MODEL });
 
     const responseText = await fetchModelResponse(hf, systemPrompt);
@@ -357,14 +393,7 @@ export async function POST(req: NextRequest) {
 
     const parsed = parseGeneratedPayload(responseText);
     const slides = normalizeSlides(parsed.slides);
-
-    const slidesWithImages = await Promise.all(
-      slides.map(async (slide) => {
-        if (slide.layout !== 'image_and_text' || !slide.imageKeyword) return slide;
-        const imageUrl = await fetchImageForSlide(slide.imageKeyword);
-        return { ...slide, imageUrl };
-      })
-    );
+    const slidesWithImages = await attachImagesToSlides(slides);
 
     return NextResponse.json({
       presentationName: parsed.presentationName || presentationName,

app/page.tsx

@@ -1 +1,8 @@
+/*
+ * page.tsx
+ * Purpose: Exposes the landing page component at the root route without adding extra route logic.
+ * Used by: Next.js router for /.
+ * Depends on: components/home/HomePage.
+ */
+
 export { default } from '@/components/home/HomePage';

app/template/page.tsx

@@ -1,3 +1,10 @@
+/*
+ * page.tsx
+ * Purpose: Renders the template-preview route used to inspect available slide themes/layouts.
+ * Used by: Next.js router for /template.
+ * Depends on: template registries and preview components.
+ */
+
 'use client';
 
 import React, { useState } from 'react';

components/ThemeProvider.tsx

@@ -1,3 +1,10 @@
+/*
+ * ThemeProvider.tsx
+ * Purpose: Wraps next-themes so pages can read and toggle the global light/dark theme.
+ * Used by: app/layout.tsx and any component using useTheme.
+ * Depends on: next-themes React context.
+ */
+
 'use client';
 
 import React, { createContext, useContext, useEffect, useState } from 'react';

components/UnsplashImageSearch.tsx

@@ -1,3 +1,10 @@
+/*
+ * UnsplashImageSearch.tsx
+ * Purpose: Provides the modal UI for searching and selecting remote images for slides.
+ * Used by: GoogleSlidesEditor and template image-selection flows.
+ * Depends on: search/download API routes and editor callbacks.
+ */
+
 'use client';
 
 import React, { useEffect, useState } from 'react';

components/editor/AIToolsDialog.tsx

@@ -1,3 +1,10 @@
+/*
+ * AIToolsDialog.tsx
+ * Purpose: Shows the focused text-editing dialog for refine/change/expand/regenerate AI actions.
+ * Used by: GoogleSlidesEditor when a text element is edited with AI.
+ * Depends on: AI edit route and editor apply callbacks.
+ */
+
 import React, { useState } from 'react';
 import { X, Sparkles, RefreshCw, FileText, Maximize2 } from 'lucide-react';
 

components/editor/BottomToolbar.tsx

@@ -1,3 +1,10 @@
+/*
+ * BottomToolbar.tsx
+ * Purpose: Renders the floating editor toolbar for layout, typography, AI tools, zoom, and slide actions.
+ * Used by: GoogleSlidesEditor.
+ * Depends on: Editor selection state, formatting callbacks, and toolbar menu state.
+ */
+
 import React from "react";
 import {
     ChevronDown,

components/editor/GoogleSlidesEditor.tsx

@@ -1,3 +1,12 @@
+/*
+ * GoogleSlidesEditor.tsx
+ * Purpose: Hosts the main presentation workspace, including generation bootstrap,
+ * editor state, canvas rendering, slide management, and export entry points.
+ * Used by: app/editor/page.tsx
+ * Depends on: generation API routes, SlideFactory/template registries, editor hooks,
+ * theme definitions, and export helpers.
+ */
+
 'use client';
 
 import React, { useCallback, useEffect, useRef, useState } from 'react';
@@ -36,6 +45,97 @@ import {
   isPresentationGenerateSuccessResponse,
   mapPresentationSlidesToSlideSpecs,
 } from '@/lib/generated-presentation';
+import type { PresentationApiSlide } from '@/lib/generated-presentation';
+
+type ActiveEditorTheme = (typeof themes)[keyof typeof themes];
+
+function getGeneratedSlideText(spec: SlideSpec) {
+  return spec.items?.map((item) => item.text).join('\n\n')
+    || spec.body?.map((entry) => entry.text).join('\n\n')
+    || spec.subtitle
+    || '';
+}
+
+function createTextElement(
+  content: string,
+  activeTheme: ActiveEditorTheme,
+  fontFamily: string,
+  position: { x: number; y: number; width: number; height: number; fontSize: number },
+  fontWeight: 'normal' | 'bold' = 'normal'
+): TextElement {
+  return {
+    id: createId(),
+    type: 'text',
+    x: position.x,
+    y: position.y,
+    width: position.width,
+    height: position.height,
+    text: content,
+    fontSize: position.fontSize,
+    color: fontWeight === 'bold' ? activeTheme.titleColor : activeTheme.textColor,
+    fontWeight,
+    fontStyle: 'normal',
+    textDecoration: 'none',
+    align: 'left',
+    fontFamily,
+  };
+}
+
+function buildGeneratedSlideElements(
+  spec: SlideSpec,
+  sourceSlide: PresentationApiSlide,
+  slideIndex: number,
+  activeTheme: ActiveEditorTheme
+): EditorElement[] {
+  const headingFont = activeTheme.headingFont || 'Arial';
+  const bodyFont = activeTheme.bodyFont || 'Arial';
+  const title = spec.title || `Slide ${slideIndex + 1}`;
+  const contentText = getGeneratedSlideText(spec);
+
+  if (spec.layout === 'image_and_text' && sourceSlide.imageUrl) {
+    return [
+      createTextElement(title, activeTheme, headingFont, { x: 60, y: 40, width: 680, height: 60, fontSize: 36 }, 'bold'),
+      createTextElement(contentText, activeTheme, bodyFont, { x: 60, y: 120, width: 340, height: 280, fontSize: 18 }),
+      {
+        id: createId(),
+        type: 'image',
+        x: 440,
+        y: 120,
+        width: 300,
+        height: 280,
+        src: sourceSlide.imageUrl,
+        maintainAspectRatio: true,
+      } as ImageElement,
+    ];
+  }
+
+  if (spec.layout === 'three_columns' && Array.isArray(spec.columns) && spec.columns.length > 0) {
+    return [
+      createTextElement(title, activeTheme, headingFont, { x: 50, y: 30, width: 700, height: 50, fontSize: 34 }, 'bold'),
+      ...spec.columns.slice(0, 3).flatMap((column, columnIndex) => {
+        const x = 45 + (columnIndex * 245);
+        return [
+          createTextElement(column.heading || `Column ${columnIndex + 1}`, activeTheme, headingFont, { x, y: 115, width: 210, height: 45, fontSize: 22 }, 'bold'),
+          createTextElement(column.text || '', activeTheme, bodyFont, { x, y: 175, width: 210, height: 190, fontSize: 16 }),
+        ];
+      }),
+    ];
+  }
+
+  if (spec.layout === 'title_subtitle' || spec.layout === 'thank_you') {
+    return [
+      createTextElement(title, activeTheme, headingFont, { x: 60, y: 40, width: 680, height: 60, fontSize: 36 }, 'bold'),
+      ...(contentText
+        ? [createTextElement(contentText, activeTheme, bodyFont, { x: 60, y: 120, width: 680, height: 280, fontSize: 20 })]
+        : []),
+    ];
+  }
+
+  return [
+    createTextElement(title, activeTheme, headingFont, { x: 60, y: 40, width: 680, height: 60, fontSize: 36 }, 'bold'),
+    createTextElement(contentText, activeTheme, bodyFont, { x: 60, y: 120, width: 680, height: 280, fontSize: 20 }),
+  ];
+}
 
 export default function GoogleSlidesEditor() {
   // Presentation data
@@ -239,200 +339,14 @@ export default function GoogleSlidesEditor() {
             throw new Error('Generation returned no slides.');
           }
 
-          // Transform API response to editor format
+          // Translate the generated slide specs into positioned editor elements for legacy canvas mode.
           const activeTheme = themes[resolvedTheme];
-          const headingFont = activeTheme.headingFont || 'Arial';
-          const bodyFont = activeTheme.bodyFont || 'Arial';
           const generatedSlides: SlideModel[] = data.slides.map((slide, index) => {
             const spec = specs[index];
-            const layout = spec.layout;
-            const contentText = spec.items?.map((item) => item.text).join('\n\n')
-              || spec.body?.map((entry) => entry.text).join('\n\n')
-              || spec.subtitle
-              || '';
-            let elements: EditorElement[] = [];
-
-            if (layout === 'image_and_text' && slide.imageUrl) {
-              elements = [
-                {
-                  id: createId(),
-                  type: 'text',
-                  x: 60,
-                  y: 40,
-                  width: 680,
-                  height: 60,
-                  text: spec.title || `Slide ${index + 1}`,
-                  fontSize: 36,
-                  color: activeTheme.titleColor,
-                  fontWeight: 'bold',
-                  fontStyle: 'normal',
-                  textDecoration: 'none',
-                  align: 'left',
-                  fontFamily: headingFont,
-                } as TextElement,
-                {
-                  id: createId(),
-                  type: 'text',
-                  x: 60,
-                  y: 120,
-                  width: 340,
-                  height: 280,
-                  text: contentText,
-                  fontSize: 18,
-                  color: activeTheme.textColor,
-                  fontWeight: 'normal',
-                  fontStyle: 'normal',
-                  textDecoration: 'none',
-                  align: 'left',
-                  fontFamily: bodyFont,
-                } as TextElement,
-                {
-                  id: createId(),
-                  type: 'image',
-                  x: 440,
-                  y: 120,
-                  width: 300,
-                  height: 280,
-                  src: slide.imageUrl,
-                  maintainAspectRatio: true,
-                } as ImageElement
-              ];
-            } else if (layout === 'three_columns' && Array.isArray(spec.columns) && spec.columns.length > 0) {
-              elements = [
-                {
-                  id: createId(),
-                  type: 'text',
-                  x: 50,
-                  y: 30,
-                  width: 700,
-                  height: 50,
-                  text: spec.title || `Slide ${index + 1}`,
-                  fontSize: 34,
-                  color: activeTheme.titleColor,
-                  fontWeight: 'bold',
-                  fontStyle: 'normal',
-                  textDecoration: 'none',
-                  align: 'left',
-                  fontFamily: headingFont,
-                } as TextElement,
-                ...spec.columns.slice(0, 3).flatMap((column, columnIndex: number) => {
-                  const x = 45 + (columnIndex * 245);
-                  return [
-                    {
-                      id: createId(),
-                      type: 'text',
-                      x,
-                      y: 115,
-                      width: 210,
-                      height: 45,
-                      text: column.heading || `Column ${columnIndex + 1}`,
-                      fontSize: 22,
-                      color: activeTheme.titleColor,
-                      fontWeight: 'bold',
-                      fontStyle: 'normal',
-                      textDecoration: 'none',
-                      align: 'left',
-                      fontFamily: headingFont,
-                    } as TextElement,
-                    {
-                      id: createId(),
-                      type: 'text',
-                      x,
-                      y: 175,
-                      width: 210,
-                      height: 190,
-                      text: column.text || '',
-                      fontSize: 16,
-                      color: activeTheme.textColor,
-                      fontWeight: 'normal',
-                      fontStyle: 'normal',
-                      textDecoration: 'none',
-                      align: 'left',
-                      fontFamily: bodyFont,
-                    } as TextElement,
-                  ];
-                }),
-              ];
-            } else if (layout === 'title_subtitle' || layout === 'thank_you') {
-              const subtitleElement = contentText
-                ? [{
-                  id: createId(),
-                  type: 'text',
-                  x: 60,
-                  y: 120,
-                  width: 680,
-                  height: 280,
-                  text: contentText,
-                  fontSize: 20,
-                  color: activeTheme.textColor,
-                  fontWeight: 'normal',
-                  fontStyle: 'normal',
-                  textDecoration: 'none',
-                  align: 'left',
-                  fontFamily: bodyFont,
-                } as TextElement]
-                : [];
-
-              elements = [
-                {
-                  id: createId(),
-                  type: 'text',
-                  x: 60,
-                  y: 40,
-                  width: 680,
-                  height: 60,
-                  text: spec.title || `Slide ${index + 1}`,
-                  fontSize: 36,
-                  color: activeTheme.titleColor,
-                  fontWeight: 'bold',
-                  fontStyle: 'normal',
-                  textDecoration: 'none',
-                  align: 'left',
-                  fontFamily: headingFont,
-                } as TextElement,
-                ...subtitleElement,
-              ];
-            } else {
-              elements = [
-                {
-                  id: createId(),
-                  type: 'text',
-                  x: 60,
-                  y: 40,
-                  width: 680,
-                  height: 60,
-                  text: spec.title || `Slide ${index + 1}`,
-                  fontSize: 36,
-                  color: activeTheme.titleColor,
-                  fontWeight: 'bold',
-                  fontStyle: 'normal',
-                  textDecoration: 'none',
-                  align: 'left',
-                  fontFamily: headingFont,
-                } as TextElement,
-                {
-                  id: createId(),
-                  type: 'text',
-                  x: 60,
-                  y: 120,
-                  width: 680,
-                  height: 280,
-                  text: contentText,
-                  fontSize: 20,
-                  color: activeTheme.textColor,
-                  fontWeight: 'normal',
-                  fontStyle: 'normal',
-                  textDecoration: 'none',
-                  align: 'left',
-                  fontFamily: bodyFont,
-                } as TextElement
-              ];
-            }
-
             return {
               id: createId(),
-              layout,
-              elements,
+              layout: spec.layout,
+              elements: buildGeneratedSlideElements(spec, slide, index, activeTheme),
             };
           });
 

components/home/HomePage.tsx

@@ -1,90 +1,158 @@
+/*
+ * HomePage.tsx
+ * Purpose: Renders the public landing page, restores Hugging Face auth state, and
+ * prepares the session data that hands a generation request off to the editor route.
+ * Used by: app/page.tsx
+ * Depends on: ThemeProvider, Hugging Face OAuth helpers, template option helpers,
+ * and the editor route's sessionStorage contract.
+ */
+
 'use client';
 
-import React, { useState, useRef, useEffect } from 'react';
+import React, { useEffect, useRef, useState } from 'react';
 import { useRouter } from 'next/navigation';
 import { LogIn, Moon, Sun, ArrowUp, Check, ChevronDown, User, LogOut } from 'lucide-react';
-import { useTheme } from '@/components/ThemeProvider';
 import { oauthLoginUrl, oauthHandleRedirectIfPresent } from '@huggingface/hub';
+import { useTheme } from '@/components/ThemeProvider';
 import { LLAMA_PRESENTATION_MODEL } from '@/lib/ai-models';
-import { TEMPLATE_OPTIONS, TemplateOptionId, getTemplateLabel, normalizeTemplateId } from '@/lib/template-options';
+import {
+  TEMPLATE_OPTIONS,
+  TemplateOptionId,
+  getTemplateLabel,
+  normalizeTemplateId,
+} from '@/lib/template-options';
+
+type AuthenticatedUser = {
+  name: string;
+  avatarUrl?: string;
+};
+
+type StoredOAuthSession = {
+  accessToken?: string;
+  accessTokenExpiresAt?: string;
+  userInfo?: {
+    name?: string;
+    preferred_username?: string;
+    avatarUrl?: string;
+    picture?: string;
+  };
+};
+
+function clearStoredAuthSession() {
+  localStorage.removeItem('hf_oauth');
+  localStorage.removeItem('hf_api_key');
+  sessionStorage.removeItem('editorAccess');
+}
+
+function restoreStoredUser(): AuthenticatedUser | null {
+  const storedSession = localStorage.getItem('hf_oauth');
+  if (!storedSession) return null;
+
+  try {
+    const parsed = JSON.parse(storedSession) as StoredOAuthSession;
+    const expiresAt = parsed.accessTokenExpiresAt ? new Date(parsed.accessTokenExpiresAt) : null;
+    const isTokenValid = Boolean(parsed.accessToken && expiresAt && expiresAt > new Date());
+
+    if (!isTokenValid) {
+      clearStoredAuthSession();
+      return null;
+    }
+
+    localStorage.setItem('hf_api_key', parsed.accessToken as string);
+    return {
+      name: parsed.userInfo?.name || parsed.userInfo?.preferred_username || 'Hugging Face User',
+      avatarUrl: parsed.userInfo?.avatarUrl || parsed.userInfo?.picture || '',
+    };
+  } catch {
+    clearStoredAuthSession();
+    return null;
+  }
+}
+
+function persistOAuthRedirectSession(result: Awaited<ReturnType<typeof oauthHandleRedirectIfPresent>>) {
+  if (!result) return null;
+
+  const oauthUser = result.userInfo as {
+    preferred_username?: string;
+    name?: string;
+    picture?: string;
+    avatarUrl?: string;
+    email?: string;
+  };
+
+  const storedSession = {
+    accessToken: result.accessToken,
+    accessTokenExpiresAt: result.accessTokenExpiresAt,
+    userInfo: {
+      name: oauthUser.preferred_username || oauthUser.name,
+      fullname: oauthUser.name || '',
+      avatarUrl: oauthUser.picture || oauthUser.avatarUrl || '',
+      email: oauthUser.email,
+    },
+  };
+
+  localStorage.setItem('hf_oauth', JSON.stringify(storedSession));
+  localStorage.setItem('hf_api_key', result.accessToken);
+
+  return {
+    name: storedSession.userInfo.name || 'Hugging Face User',
+    avatarUrl: storedSession.userInfo.avatarUrl,
+  };
+}
+
+function isHuggingFaceSpacesRuntime() {
+  const hostname = window.location.hostname;
+  const isEmbedded = window.self !== window.top;
+  const isSpaceHost = hostname.endsWith('.hf.space') || hostname === 'huggingface.co';
+  return isSpaceHost || isEmbedded;
+}
 
 export default function HomePage() {
+  const router = useRouter();
+  const { theme, setTheme } = useTheme();
+
   const [prompt, setPrompt] = useState('');
   const [template, setTemplate] = useState<TemplateOptionId>('neobrutalism');
   const [isGenerating, setIsGenerating] = useState(false);
   const [isSelectOpen, setIsSelectOpen] = useState(false);
-  const [user, setUser] = useState<{ name: string; avatarUrl?: string } | null>(null);
+  const [user, setUser] = useState<AuthenticatedUser | null>(null);
   const [submitError, setSubmitError] = useState<string | null>(null);
   const [isAuthReady, setIsAuthReady] = useState(false);
   const [isHuggingFaceSpace, setIsHuggingFaceSpace] = useState(false);
+  const [mounted, setMounted] = useState(false);
+
   const textareaRef = useRef<HTMLTextAreaElement>(null);
   const selectRef = useRef<HTMLDivElement>(null);
-  const { theme, setTheme } = useTheme();
-  const [mounted, setMounted] = useState(false);
 
+  // Restore the saved template choice and hydrate the browser-only auth/session state.
   useEffect(() => {
     setMounted(true);
-    const hostname = window.location.hostname;
-    const isEmbedded = window.self !== window.top;
-    const isSpaceHost = hostname.endsWith('.hf.space') || hostname === 'huggingface.co';
-    setIsHuggingFaceSpace(isSpaceHost || isEmbedded);
+    setIsHuggingFaceSpace(isHuggingFaceSpacesRuntime());
 
     const savedTemplate = normalizeTemplateId(localStorage.getItem('ppt_theme'));
     if (savedTemplate) {
       setTemplate(savedTemplate);
     }
-    
+
     const initializeAuth = async () => {
       try {
-        // Check stored auth
-        const stored = localStorage.getItem('hf_oauth');
-        if (stored) {
-          try {
-            const parsed = JSON.parse(stored);
-            const expiresAt = parsed.accessTokenExpiresAt ? new Date(parsed.accessTokenExpiresAt) : null;
-
-            if (expiresAt && expiresAt > new Date() && parsed.accessToken) {
-              setUser({
-                name: parsed.userInfo.name || parsed.userInfo.preferred_username,
-                avatarUrl: parsed.userInfo.avatarUrl || parsed.userInfo.picture || '',
-              });
-              localStorage.setItem('hf_api_key', parsed.accessToken);
-              setSubmitError(null);
-            } else {
-              localStorage.removeItem('hf_oauth');
-              localStorage.removeItem('hf_api_key');
-              sessionStorage.removeItem('editorAccess');
-            }
-          } catch {
-            localStorage.removeItem('hf_oauth');
-            localStorage.removeItem('hf_api_key');
-            sessionStorage.removeItem('editorAccess');
-          }
+        const restoredUser = restoreStoredUser();
+        if (restoredUser) {
+          setUser(restoredUser);
+          setSubmitError(null);
         }
 
-        // Handle redirect
-        const result = await oauthHandleRedirectIfPresent();
-        if (result) {
-          const ui = result.userInfo as any;
-          const userData = {
-            accessToken: result.accessToken,
-            accessTokenExpiresAt: result.accessTokenExpiresAt,
-            userInfo: {
-              name: ui.preferred_username || ui.name,
-              fullname: ui.name || '',
-              avatarUrl: ui.picture || ui.avatarUrl || '',
-              email: ui.email,
-            }
-          };
-          localStorage.setItem('hf_oauth', JSON.stringify(userData));
-          localStorage.setItem('hf_api_key', result.accessToken);
-          setUser({ name: userData.userInfo.name, avatarUrl: userData.userInfo.avatarUrl });
+        // Handle the post-login redirect on the home route and persist it like a refreshable session.
+        const redirectResult = await oauthHandleRedirectIfPresent();
+        const redirectedUser = persistOAuthRedirectSession(redirectResult);
+
+        if (redirectedUser) {
+          setUser(redirectedUser);
           setSubmitError(null);
-          // Clean URL
           window.history.replaceState({}, document.title, window.location.pathname);
         }
-      } catch (err) {
-        console.error('OAuth error:', err);
+      } catch (error) {
+        console.error('OAuth error:', error);
       } finally {
         setIsAuthReady(true);
       }
@@ -95,21 +163,25 @@ export default function HomePage() {
 
   const handleSignIn = async () => {
     try {
-      const res = await fetch('/api/auth/client-id');
-      const { clientId } = await res.json();
+      const response = await fetch('/api/auth/client-id');
+      const { clientId } = await response.json();
+
       if (!clientId) {
-        console.error('HuggingFace Client ID not configured');
+        console.error('Hugging Face client ID not configured');
         return;
       }
+
       const loginUrl = await oauthLoginUrl({
         clientId,
         scopes: 'openid profile inference-api',
         redirectUrl: `${window.location.origin}/`,
       });
+
       const destination = `${loginUrl}&prompt=consent`;
+
+      // Space embeds can block same-frame navigation, so prefer escaping the iframe shell.
       if (isHuggingFaceSpace) {
         const topNavigation = window.open(destination, '_top');
-
         if (!topNavigation) {
           window.open(destination, '_blank', 'noopener,noreferrer');
         }
@@ -117,24 +189,19 @@ export default function HomePage() {
       }
 
       window.location.assign(destination);
-    } catch (err) {
-      console.error('Sign in error:', err);
+    } catch (error) {
+      console.error('Sign in error:', error);
     }
   };
 
   const handleSignOut = () => {
-    localStorage.removeItem('hf_oauth');
-    localStorage.removeItem('hf_api_key');
-    sessionStorage.removeItem('editorAccess');
+    clearStoredAuthSession();
     setUser(null);
   };
 
-  const router = useRouter();
-
   const handleSubmit = () => {
     const trimmedPrompt = prompt.trim();
-    if (!trimmedPrompt) return;
-    if (!isAuthReady) return;
+    if (!trimmedPrompt || !isAuthReady) return;
 
     if (!user) {
       setSubmitError('Please log in with Hugging Face before generating a presentation.');
@@ -144,6 +211,7 @@ export default function HomePage() {
     setSubmitError(null);
     setIsGenerating(true);
 
+    // The editor route reads these keys on first load to start generation automatically.
     sessionStorage.setItem('generationPrompt', trimmedPrompt);
     sessionStorage.setItem('generationModel', LLAMA_PRESENTATION_MODEL);
     sessionStorage.setItem('isGenerating', 'true');
@@ -153,28 +221,36 @@ export default function HomePage() {
     router.push('/editor');
   };
 
-  const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
-    if (e.key === 'Enter' && !e.shiftKey) {
-      e.preventDefault();
+  const handlePromptChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {
+    setPrompt(event.target.value);
+    if (submitError) {
+      setSubmitError(null);
+    }
+  };
+
+  const handleKeyDown = (event: React.KeyboardEvent<HTMLTextAreaElement>) => {
+    if (event.key === 'Enter' && !event.shiftKey) {
+      event.preventDefault();
       handleSubmit();
     }
   };
 
-  // Auto-resize textarea
+  // Keep the prompt box compact until the content genuinely needs more room.
   useEffect(() => {
-    if (textareaRef.current) {
-      textareaRef.current.style.height = 'auto';
-      textareaRef.current.style.height = `${Math.min(textareaRef.current.scrollHeight, 300)}px`;
-    }
+    if (!textareaRef.current) return;
+
+    textareaRef.current.style.height = 'auto';
+    textareaRef.current.style.height = `${Math.min(textareaRef.current.scrollHeight, 300)}px`;
   }, [prompt]);
 
-  // Close select on click outside
+  // Close the template dropdown when the click lands outside the control cluster.
   useEffect(() => {
     const handleClickOutside = (event: MouseEvent) => {
       if (selectRef.current && !selectRef.current.contains(event.target as Node)) {
         setIsSelectOpen(false);
       }
     };
+
     document.addEventListener('mousedown', handleClickOutside);
     return () => document.removeEventListener('mousedown', handleClickOutside);
   }, []);
@@ -183,12 +259,12 @@ export default function HomePage() {
 
   return (
     <div className="min-h-screen flex flex-col bg-white dark:bg-[#09090b] selection:bg-zinc-200 dark:selection:bg-zinc-800 transition-colors duration-300 font-sans">
-      {/* Navbar */}
+      {/* Top navigation keeps theme/auth controls available before the user starts generating. */}
       <nav className={`relative z-20 flex items-center justify-between px-6 ${isHuggingFaceSpace ? 'pb-6 pt-16' : 'py-6'}`}>
         <div className="flex items-center gap-2 text-zinc-950 dark:text-zinc-50">
           <span className="text-xl font-semibold tracking-tight">Powerpoint.ai</span>
         </div>
-        
+
         <div className="flex items-center gap-6">
           <button
             onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}
@@ -197,7 +273,7 @@ export default function HomePage() {
             {theme === 'dark' ? <Sun className="h-4 w-4" /> : <Moon className="h-4 w-4" />}
             <span className="sr-only">Toggle theme</span>
           </button>
-          
+
           {user ? (
             <div className="flex items-center gap-4 group">
               <div className="flex items-center gap-2">
@@ -214,7 +290,7 @@ export default function HomePage() {
                   {user.name}
                 </span>
               </div>
-              <button 
+              <button
                 onClick={handleSignOut}
                 className="text-zinc-400 hover:text-zinc-900 dark:hover:text-zinc-50 transition-colors"
                 title="Sign Out"
@@ -223,7 +299,7 @@ export default function HomePage() {
               </button>
             </div>
           ) : (
-            <button 
+            <button
               onClick={handleSignIn}
               className="pointer-events-auto flex items-center gap-2 text-zinc-600 dark:text-zinc-400 hover:text-zinc-900 dark:hover:text-zinc-50 transition-all text-sm font-medium"
             >
@@ -234,34 +310,26 @@ export default function HomePage() {
         </div>
       </nav>
 
-      {/* Main Content */}
+      {/* The builder section keeps the landing page focused on a single action: start a deck. */}
       <main className="flex-1 flex flex-col items-center justify-center p-6 md:p-12 w-full max-w-4xl mx-auto space-y-12 mb-20">
-        
-        {/* Hero Section */}
         <div className="text-center">
           <h1 className="text-3xl md:text-4xl font-semibold tracking-tight text-zinc-900 dark:text-zinc-100">
             What kind of presentation do you need today?
           </h1>
         </div>
 
-        {/* Builder Input Section */}
         <div className="w-full max-w-3xl">
           <div className="bg-[#f4f4f5] dark:bg-[#18181b] rounded-[2rem] p-4 flex flex-col transition-all focus-within:ring-2 focus-within:ring-zinc-200 dark:focus-within:ring-zinc-800">
             <textarea
               ref={textareaRef}
               value={prompt}
-              onChange={(e) => {
-                setPrompt(e.target.value);
-                if (submitError) {
-                  setSubmitError(null);
-                }
-              }}
+              onChange={handlePromptChange}
               onKeyDown={handleKeyDown}
               placeholder="How can I help you today?"
               className="w-full min-h-[100px] bg-transparent text-zinc-900 dark:text-zinc-100 placeholder:text-zinc-500 dark:placeholder:text-zinc-500 text-lg outline-none resize-none px-4 py-2"
               style={{ overflow: 'hidden' }}
             />
-            
+
             <div className="flex items-center justify-end gap-2 mt-2 px-2 pb-2">
               <div className="relative" ref={selectRef}>
                 <button
@@ -271,7 +339,7 @@ export default function HomePage() {
                   <span className="truncate">{getTemplateLabel(template)}</span>
                   <ChevronDown className={`h-3.5 w-3.5 opacity-50 transition-transform ${isSelectOpen ? 'rotate-180' : ''}`} />
                 </button>
-                
+
                 {isSelectOpen && (
                   <div className="absolute right-0 bottom-full mb-2 z-50 min-w-[12rem] overflow-hidden rounded-xl border border-zinc-200 dark:border-zinc-800 bg-white dark:bg-[#09090b] text-zinc-950 dark:text-zinc-50 shadow-xl animate-in fade-in slide-in-from-bottom-2">
                     <div className="p-1">
@@ -294,6 +362,7 @@ export default function HomePage() {
                   </div>
                 )}
               </div>
+
               <button
                 onClick={handleSubmit}
                 disabled={!prompt.trim() || isGenerating || !isAuthReady}
@@ -303,6 +372,7 @@ export default function HomePage() {
               </button>
             </div>
           </div>
+
           {submitError && (
             <p className="mt-3 px-2 text-sm font-medium text-red-600 dark:text-red-400">
               {submitError}

components/slides/AgendaSlideLayout.tsx

@@ -1,3 +1,10 @@
+/*
+ * AgendaSlideLayout.tsx
+ * Purpose: Implements one of the generic fallback slide layouts used when a template-specific renderer is unavailable.
+ * Used by: components/slides/SlideFactory.
+ * Depends on: Template styling props and inline field-edit callbacks.
+ */
+
 'use client';
 
 import React, { useState } from 'react';

components/slides/ImageAndTextLayout.tsx

@@ -1,3 +1,10 @@
+/*
+ * ImageAndTextLayout.tsx
+ * Purpose: Implements one of the generic fallback slide layouts used when a template-specific renderer is unavailable.
+ * Used by: components/slides/SlideFactory.
+ * Depends on: Template styling props and inline field-edit callbacks.
+ */
+
 'use client';
 
 import React, { useState } from 'react';

components/slides/ReferenceLayout.tsx

@@ -1,3 +1,10 @@
+/*
+ * ReferenceLayout.tsx
+ * Purpose: Implements one of the generic fallback slide layouts used when a template-specific renderer is unavailable.
+ * Used by: components/slides/SlideFactory.
+ * Depends on: Template styling props and inline field-edit callbacks.
+ */
+
 'use client';
 
 import React, { useState } from 'react';

components/slides/SlideFactory.tsx

@@ -1,21 +1,43 @@
+/*
+ * SlideFactory.tsx
+ * Purpose: Centralizes slide rendering by mapping a SlideSpec to the correct
+ * theme-specific layout component, with generic fallback layouts as a safety net.
+ * Used by: GoogleSlidesEditor thumbnails/canvas and any code that needs to render
+ * template slides from declarative SlideSpec data.
+ * Depends on: data/templates for SlideSpec/template metadata and all slide layout components.
+ */
+
 import React from 'react';
-import { SlideSpec, getTemplateById, TemplateStyles } from '@/data/templates';
+import { SlideSpec, getTemplateById, TemplateStyles, LayoutType } from '@/data/templates';
 
-// Template-specific layout components
 import {
-  NeoTitleSubtitle, NeoAgenda, NeoTitleAndText, NeoThreeColumns,
-  NeoImageAndText, NeoReferences, NeoThankYou,
+  NeoTitleSubtitle,
+  NeoAgenda,
+  NeoTitleAndText,
+  NeoThreeColumns,
+  NeoImageAndText,
+  NeoReferences,
+  NeoThankYou,
 } from './neobrutalism/layouts';
 import {
-  NoisyTitleSubtitle, NoisyAgenda, NoisyThreeColumns, NoisyTitleAndText,
-  NoisyImageAndText, NoisyReferences, NoisyThankYou,
+  NoisyTitleSubtitle,
+  NoisyAgenda,
+  NoisyThreeColumns,
+  NoisyTitleAndText,
+  NoisyImageAndText,
+  NoisyReferences,
+  NoisyThankYou,
 } from './noisy/layouts';
 import {
-  GalerynTitleSubtitle, GalerynAgenda, GalerynThreeColumns, GalerynTitleAndText,
-  GalerynImageAndText, GalerynReferences, GalerynThankYou,
+  GalerynTitleSubtitle,
+  GalerynAgenda,
+  GalerynThreeColumns,
+  GalerynTitleAndText,
+  GalerynImageAndText,
+  GalerynReferences,
+  GalerynThankYou,
 } from './galeryn/layouts';
 
-// Generic fallback layouts
 import TitleSlideLayout from './TitleSlideLayout';
 import AgendaSlideLayout from './AgendaSlideLayout';
 import TitleAndBodyLayout from './TitleAndBodyLayout';
@@ -24,7 +46,6 @@ import ImageAndTextLayout from './ImageAndTextLayout';
 import ReferenceLayout from './ReferenceLayout';
 import ThankYouLayout from './ThankYouLayout';
 
-// Re-export SlideSpec for backward compatibility
 export type { SlideSpec } from '@/data/templates';
 
 export interface RenderSlideOptions {
@@ -34,25 +55,40 @@ export interface RenderSlideOptions {
   onFormattingUpdate?: (slideId: string, key: string, patch: Record<string, unknown>) => void;
 }
 
-/**
- * Render the correct layout component for a given slide spec.
- * Dispatches to template-specific components when available,
- * falls back to generic layouts otherwise.
- */
-export function renderSlide(
-  spec: SlideSpec,
-  _theme?: string,
-  options?: RenderSlideOptions
-): React.ReactNode {
-  const { isEditable = false, onFieldUpdate, onRequestImageSelect, onFormattingUpdate } = options || {};
+type LayoutComponent = React.ComponentType<any>;
 
-  const template = getTemplateById(spec.templateId);
-  if (!template) {
-    return <div className="w-full h-full flex items-center justify-center bg-gray-100 text-gray-500">Unknown template: {spec.templateId}</div>;
-  }
+const templateLayoutRegistry: Record<string, Partial<Record<LayoutType, LayoutComponent>>> = {
+  neobrutalism: {
+    title_subtitle: NeoTitleSubtitle as LayoutComponent,
+    agenda: NeoAgenda as LayoutComponent,
+    title_and_text: NeoTitleAndText as LayoutComponent,
+    three_columns: NeoThreeColumns as LayoutComponent,
+    image_and_text: NeoImageAndText as LayoutComponent,
+    references: NeoReferences as LayoutComponent,
+    thank_you: NeoThankYou as LayoutComponent,
+  },
+  noisy: {
+    title_subtitle: NoisyTitleSubtitle as LayoutComponent,
+    agenda: NoisyAgenda as LayoutComponent,
+    title_and_text: NoisyTitleAndText as LayoutComponent,
+    three_columns: NoisyThreeColumns as LayoutComponent,
+    image_and_text: NoisyImageAndText as LayoutComponent,
+    references: NoisyReferences as LayoutComponent,
+    thank_you: NoisyThankYou as LayoutComponent,
+  },
+  galeryn: {
+    title_subtitle: GalerynTitleSubtitle as LayoutComponent,
+    agenda: GalerynAgenda as LayoutComponent,
+    title_and_text: GalerynTitleAndText as LayoutComponent,
+    three_columns: GalerynThreeColumns as LayoutComponent,
+    image_and_text: GalerynImageAndText as LayoutComponent,
+    references: GalerynReferences as LayoutComponent,
+    thank_you: GalerynThankYou as LayoutComponent,
+  },
+};
 
-  const styles: TemplateStyles = template.styles;
-  const commonProps = {
+function buildCommonProps(spec: SlideSpec, styles: TemplateStyles, options?: RenderSlideOptions) {
+  return {
     title: spec.title || '',
     subtitle: spec.subtitle,
     body: spec.body,
@@ -62,65 +98,156 @@ export function renderSlide(
     formatting: spec.formatting,
     styles,
     slideId: spec.id,
-    isEditable,
-    onFieldUpdate,
-    onFormattingUpdate,
+    isEditable: options?.isEditable || false,
+    onFieldUpdate: options?.onFieldUpdate,
+    onFormattingUpdate: options?.onFormattingUpdate,
   };
+}
 
-  // Template-specific rendering
-  if (spec.templateId === 'neobrutalism') {
-    switch (spec.layout) {
-      case 'title_subtitle': return <NeoTitleSubtitle {...commonProps} />;
-      case 'agenda': return <NeoAgenda {...commonProps} />;
-      case 'title_and_text': return <NeoTitleAndText {...commonProps} />;
-      case 'three_columns': return <NeoThreeColumns {...commonProps} />;
-      case 'image_and_text': return <NeoImageAndText {...commonProps} onRequestImageSelect={onRequestImageSelect} />;
-      case 'references': return <NeoReferences {...commonProps} />;
-      case 'thank_you': return <NeoThankYou {...commonProps} />;
-    }
-  }
+function renderThemeSpecificLayout(
+  spec: SlideSpec,
+  commonProps: Record<string, unknown>,
+  onRequestImageSelect?: (slideId: string) => void
+) {
+  const templateLayouts = templateLayoutRegistry[spec.templateId];
+  const LayoutComponent = templateLayouts?.[spec.layout];
 
-  if (spec.templateId === 'noisy') {
-    switch (spec.layout) {
-      case 'title_subtitle': return <NoisyTitleSubtitle {...commonProps} />;
-      case 'agenda': return <NoisyAgenda {...commonProps} />;
-      case 'three_columns': return <NoisyThreeColumns {...commonProps} />;
-      case 'title_and_text': return <NoisyTitleAndText {...commonProps} />;
-      case 'image_and_text': return <NoisyImageAndText {...commonProps} onRequestImageSelect={onRequestImageSelect} />;
-      case 'references': return <NoisyReferences {...commonProps} />;
-      case 'thank_you': return <NoisyThankYou {...commonProps} />;
-    }
+  if (!LayoutComponent) {
+    return null;
   }
 
-  if (spec.templateId === 'galeryn') {
-    switch (spec.layout) {
-      case 'title_subtitle': return <GalerynTitleSubtitle {...commonProps} />;
-      case 'agenda': return <GalerynAgenda {...commonProps} />;
-      case 'three_columns': return <GalerynThreeColumns {...commonProps} />;
-      case 'title_and_text': return <GalerynTitleAndText {...commonProps} />;
-      case 'image_and_text': return <GalerynImageAndText {...commonProps} onRequestImageSelect={onRequestImageSelect} />;
-      case 'references': return <GalerynReferences {...commonProps} />;
-      case 'thank_you': return <GalerynThankYou {...commonProps} />;
-    }
+  if (spec.layout === 'image_and_text') {
+    return <LayoutComponent {...commonProps} onRequestImageSelect={onRequestImageSelect} />;
   }
 
-  // Generic fallback for unknown templates
+  return <LayoutComponent {...commonProps} />;
+}
+
+function renderFallbackLayout(
+  spec: SlideSpec,
+  styles: TemplateStyles,
+  options?: RenderSlideOptions
+) {
   switch (spec.layout) {
     case 'title_subtitle':
-      return <TitleSlideLayout title={spec.title || ''} subtitle={spec.subtitle} styles={styles} slideId={spec.id} isEditable={isEditable} onFieldUpdate={onFieldUpdate} />;
+      return (
+        <TitleSlideLayout
+          title={spec.title || ''}
+          subtitle={spec.subtitle}
+          styles={styles}
+          slideId={spec.id}
+          isEditable={options?.isEditable}
+          onFieldUpdate={options?.onFieldUpdate}
+        />
+      );
     case 'agenda':
-      return <AgendaSlideLayout title={spec.title || ''} items={spec.items || []} styles={styles} slideId={spec.id} isEditable={isEditable} onFieldUpdate={onFieldUpdate} />;
+      return (
+        <AgendaSlideLayout
+          title={spec.title || ''}
+          items={spec.items || []}
+          styles={styles}
+          slideId={spec.id}
+          isEditable={options?.isEditable}
+          onFieldUpdate={options?.onFieldUpdate}
+        />
+      );
     case 'title_and_text':
-      return <TitleAndBodyLayout title={spec.title || ''} body={spec.body || []} styles={styles} slideId={spec.id} isEditable={isEditable} onFieldUpdate={onFieldUpdate} />;
+      return (
+        <TitleAndBodyLayout
+          title={spec.title || ''}
+          body={spec.body || []}
+          styles={styles}
+          slideId={spec.id}
+          isEditable={options?.isEditable}
+          onFieldUpdate={options?.onFieldUpdate}
+        />
+      );
     case 'three_columns':
-      return <ThreeColumnLayout title={spec.title || ''} columns={spec.columns || []} styles={styles} slideId={spec.id} isEditable={isEditable} onFieldUpdate={onFieldUpdate} />;
+      return (
+        <ThreeColumnLayout
+          title={spec.title || ''}
+          columns={spec.columns || []}
+          styles={styles}
+          slideId={spec.id}
+          isEditable={options?.isEditable}
+          onFieldUpdate={options?.onFieldUpdate}
+        />
+      );
     case 'image_and_text':
-      return <ImageAndTextLayout title={spec.title || ''} body={spec.body?.[0]?.text || spec.subtitle || ''} imageUrl={spec.imageUrl} styles={styles} slideId={spec.id} isEditable={isEditable} onFieldUpdate={onFieldUpdate} />;
+      return (
+        <ImageAndTextLayout
+          title={spec.title || ''}
+          body={spec.body?.[0]?.text || spec.subtitle || ''}
+          imageUrl={spec.imageUrl}
+          styles={styles}
+          slideId={spec.id}
+          isEditable={options?.isEditable}
+          onFieldUpdate={options?.onFieldUpdate}
+        />
+      );
     case 'references':
-      return <ReferenceLayout title={spec.title || ''} items={spec.items || []} styles={styles} slideId={spec.id} isEditable={isEditable} onFieldUpdate={onFieldUpdate} />;
+      return (
+        <ReferenceLayout
+          title={spec.title || ''}
+          items={spec.items || []}
+          styles={styles}
+          slideId={spec.id}
+          isEditable={options?.isEditable}
+          onFieldUpdate={options?.onFieldUpdate}
+        />
+      );
     case 'thank_you':
-      return <ThankYouLayout title={spec.title || ''} subtitle={spec.subtitle} styles={styles} slideId={spec.id} isEditable={isEditable} onFieldUpdate={onFieldUpdate} />;
+      return (
+        <ThankYouLayout
+          title={spec.title || ''}
+          subtitle={spec.subtitle}
+          styles={styles}
+          slideId={spec.id}
+          isEditable={options?.isEditable}
+          onFieldUpdate={options?.onFieldUpdate}
+        />
+      );
     default:
-      return <TitleSlideLayout title={spec.title || 'Slide'} subtitle={spec.subtitle} styles={styles} slideId={spec.id} isEditable={isEditable} onFieldUpdate={onFieldUpdate} />;
+      return (
+        <TitleSlideLayout
+          title={spec.title || 'Slide'}
+          subtitle={spec.subtitle}
+          styles={styles}
+          slideId={spec.id}
+          isEditable={options?.isEditable}
+          onFieldUpdate={options?.onFieldUpdate}
+        />
+      );
   }
 }
+
+/**
+ * Converts a declarative slide spec into a rendered React layout.
+ * Theme-specific layouts are preferred, while generic layouts ensure the editor
+ * can still render a slide if a template-specific component is missing.
+ */
+export function renderSlide(
+  spec: SlideSpec,
+  _theme?: string,
+  options?: RenderSlideOptions
+): React.ReactNode {
+  const template = getTemplateById(spec.templateId);
+
+  if (!template) {
+    return (
+      <div className="w-full h-full flex items-center justify-center bg-gray-100 text-gray-500">
+        Unknown template: {spec.templateId}
+      </div>
+    );
+  }
+
+  const styles: TemplateStyles = template.styles;
+  const commonProps = buildCommonProps(spec, styles, options);
+  const themeSpecificLayout = renderThemeSpecificLayout(spec, commonProps, options?.onRequestImageSelect);
+
+  if (themeSpecificLayout) {
+    return themeSpecificLayout;
+  }
+
+  return renderFallbackLayout(spec, styles, options);
+}

components/slides/ThankYouLayout.tsx

@@ -1,3 +1,10 @@
+/*
+ * ThankYouLayout.tsx
+ * Purpose: Implements one of the generic fallback slide layouts used when a template-specific renderer is unavailable.
+ * Used by: components/slides/SlideFactory.
+ * Depends on: Template styling props and inline field-edit callbacks.
+ */
+
 'use client';
 
 import React, { useState } from 'react';

components/slides/ThreeColumnLayout.tsx

@@ -1,3 +1,10 @@
+/*
+ * ThreeColumnLayout.tsx
+ * Purpose: Implements one of the generic fallback slide layouts used when a template-specific renderer is unavailable.
+ * Used by: components/slides/SlideFactory.
+ * Depends on: Template styling props and inline field-edit callbacks.
+ */
+
 'use client';
 
 import React, { useState } from 'react';

components/slides/TitleAndBodyLayout.tsx

@@ -1,3 +1,10 @@
+/*
+ * TitleAndBodyLayout.tsx
+ * Purpose: Implements one of the generic fallback slide layouts used when a template-specific renderer is unavailable.
+ * Used by: components/slides/SlideFactory.
+ * Depends on: Template styling props and inline field-edit callbacks.
+ */
+
 'use client';
 
 import React, { useState } from 'react';

components/slides/TitleSlideLayout.tsx

@@ -1,3 +1,10 @@
+/*
+ * TitleSlideLayout.tsx
+ * Purpose: Implements one of the generic fallback slide layouts used when a template-specific renderer is unavailable.
+ * Used by: components/slides/SlideFactory.
+ * Depends on: Template styling props and inline field-edit callbacks.
+ */
+
 'use client';
 
 import React, { useState } from 'react';

components/slides/galeryn/layouts.tsx

@@ -1,3 +1,10 @@
+/*
+ * layouts.tsx
+ * Purpose: Defines the Galeryn theme-specific slide layout components.
+ * Used by: components/slides/SlideFactory.
+ * Depends on: Galeryn template styles and shared editable-field helpers.
+ */
+
 'use client';
 
 import React, { useEffect, useRef } from 'react';

components/slides/neobrutalism/layouts.tsx

@@ -1,3 +1,10 @@
+/*
+ * layouts.tsx
+ * Purpose: Defines the Neo-Brutalism theme-specific slide layout components.
+ * Used by: components/slides/SlideFactory.
+ * Depends on: Neo-Brutalism template styles and shared editable-field helpers.
+ */
+
 'use client';
 
 import React, { useRef, useState } from 'react';

components/slides/noisy/layouts.tsx

@@ -1,3 +1,10 @@
+/*
+ * layouts.tsx
+ * Purpose: Defines the Noisy/Distortion theme-specific slide layout components.
+ * Used by: components/slides/SlideFactory.
+ * Depends on: Noisy template styles and shared editable-field helpers.
+ */
+
 'use client';
 
 import React, { useEffect, useId, useRef } from 'react';

components/slides/shared/PersistedDraggableSurface.tsx

@@ -1,3 +1,10 @@
+/*
+ * PersistedDraggableSurface.tsx
+ * Purpose: Provides the reusable editable/draggable surface logic shared by slide layouts that persist field placement.
+ * Used by: Theme-specific slide layout components.
+ * Depends on: React drag/edit state and slide field update callbacks.
+ */
+
 'use client';
 
 import React, { createContext, useContext, useEffect, useMemo, useRef, useState } from 'react';

components/ui/empty.tsx

@@ -1,3 +1,10 @@
+/*
+ * empty.tsx
+ * Purpose: Contains reusable empty/loading state primitives used throughout the app.
+ * Used by: Editor loading/error states and any view that needs a structured empty state.
+ * Depends on: Shared UI styling helpers.
+ */
+
 import * as React from "react"
 import { cn } from "@/lib/utils"
 

components/ui/spinner.tsx

@@ -1,3 +1,10 @@
+/*
+ * spinner.tsx
+ * Purpose: Provides the small reusable loading spinner component.
+ * Used by: Editor loading states and any async UI state.
+ * Depends on: React props and shared styling.
+ */
+
 import * as React from "react"
 import { cn } from "@/lib/utils"
 

data/templates/galeryn.ts

@@ -1,3 +1,10 @@
+/*
+ * galeryn.ts
+ * Purpose: Declares one presentation template, including its styles, layouts, and default field values.
+ * Used by: data/templates/index.ts and the template-driven editor/render pipeline.
+ * Depends on: Template type definitions from data/templates/index.ts.
+ */
+
 import { Template } from './index';
 
 export const galerynTemplate: Template = {

data/templates/index.ts

@@ -1,3 +1,10 @@
+/*
+ * index.ts
+ * Purpose: Acts as the template registry and shared type definition source for template-driven slides.
+ * Used by: SlideFactory, GoogleSlidesEditor, and template-option helpers.
+ * Depends on: Individual template definition files.
+ */
+
 import { neoBrutalismTemplate } from './neo-brutalism';
 import { galerynTemplate } from './galeryn';
 import { noisyTemplate } from './noisy';

data/templates/neo-brutalism.ts

@@ -1,3 +1,10 @@
+/*
+ * neo-brutalism.ts
+ * Purpose: Declares one presentation template, including its styles, layouts, and default field values.
+ * Used by: data/templates/index.ts and the template-driven editor/render pipeline.
+ * Depends on: Template type definitions from data/templates/index.ts.
+ */
+
 import { Template } from './index';
 
 export const neoBrutalismTemplate: Template = {

data/templates/noisy.ts

@@ -1,3 +1,10 @@
+/*
+ * noisy.ts
+ * Purpose: Declares one presentation template, including its styles, layouts, and default field values.
+ * Used by: data/templates/index.ts and the template-driven editor/render pipeline.
+ * Depends on: Template type definitions from data/templates/index.ts.
+ */
+
 import { Template } from './index';
 
 export const noisyTemplate: Template = {

hooks/useExport.ts

@@ -1,3 +1,11 @@
+/*
+ * useExport.ts
+ * Purpose: Wraps the presentation export flow so the editor can trigger a PPTX
+ * download without owning the file-generation details.
+ * Used by: GoogleSlidesEditor
+ * Depends on: editable-pptx-export and the editor's current slide/theme state.
+ */
+
 import type { SlideModel } from '@/lib/editor-types';
 import { themes } from '@/lib/editor-themes';
 import type { SlideSpec } from '@/data/templates';
@@ -12,10 +20,15 @@ interface UseExportParams {
 }
 
 export function useExport({
-  slideRef, slides, slideSpecs, currentTheme,
+  slideRef,
+  slides,
+  slideSpecs,
+  currentTheme,
   presentationTitle,
 }: UseExportParams) {
   const exportToPPTX = async () => {
+    // The editor only exposes export once a canvas exists, but this guard keeps the
+    // hook resilient if the button is triggered during an intermediate render state.
     if (!slideRef.current || slides.length === 0) return;
 
     try {

hooks/useKeyboardShortcuts.ts

@@ -1,3 +1,10 @@
+/*
+ * useKeyboardShortcuts.ts
+ * Purpose: Encapsulates keyboard shortcut handling for editor selection, formatting, and undo/redo actions.
+ * Used by: GoogleSlidesEditor.
+ * Depends on: Window keyboard events and editor mutation callbacks.
+ */
+
 import { useEffect } from 'react';
 import type { TextElement, EditorElement } from '@/lib/editor-types';
 

hooks/useSlideHistory.ts

@@ -1,3 +1,10 @@
+/*
+ * useSlideHistory.ts
+ * Purpose: Stores undo/redo history for the editor slide state.
+ * Used by: GoogleSlidesEditor.
+ * Depends on: React state snapshots of the current slide collection.
+ */
+
 import { useState, useRef, useCallback, useEffect } from 'react';
 import type { SlideModel } from '@/lib/editor-types';
 

lib/ai-models.ts

@@ -1,3 +1,10 @@
+/*
+ * ai-models.ts
+ * Purpose: Defines the approved AI models and model validation helpers used by generation/edit routes.
+ * Used by: HomePage, generation routes, and HF client setup.
+ * Depends on: Shared model constants.
+ */
+
 export const LLAMA_PRESENTATION_MODEL = 'meta-llama/Llama-3.3-70B-Instruct:hf-inference';
 export const LLAMA_PRESENTATION_PROVIDER = 'hf' as const;
 

lib/capture-element.ts

@@ -1,3 +1,10 @@
+/*
+ * capture-element.ts
+ * Purpose: Captures DOM slide content as an image while handling cross-origin-safe image loading.
+ * Used by: Export and image-capture flows.
+ * Depends on: html-to-image style capture logic and the image proxy route.
+ */
+
 interface CaptureOptions {
   scale?: number;
 }

lib/editable-pptx-export.ts

@@ -1,3 +1,10 @@
+/*
+ * editable-pptx-export.ts
+ * Purpose: Builds an editable PowerPoint file from the current slide/editor state.
+ * Used by: hooks/useExport.
+ * Depends on: pptxgenjs, editor types, and template/theme helpers.
+ */
+
 import PptxGenJS from 'pptxgenjs';
 import { getTemplateById, type SlideSpec } from '@/data/templates';
 import type { SlideModel, TextElement, ImageElement, ShapeElement } from '@/lib/editor-types';

lib/editor-themes.ts

@@ -1,3 +1,10 @@
+/*
+ * editor-themes.ts
+ * Purpose: Defines the editor theme palette/font registry that powers non-template canvas rendering.
+ * Used by: GoogleSlidesEditor, export helpers, and layout background utilities.
+ * Depends on: Theme constants and PowerPoint-compatible font lists.
+ */
+
 export const TEMPLATE_THEMES = new Set<string>(['neobrutalism', 'galeryn', 'noisy']);
 
 // Theme definitions - Includes gradients, patterns, and image-based themes

lib/editor-types.ts

@@ -1,3 +1,10 @@
+/*
+ * editor-types.ts
+ * Purpose: Contains the shared editor model types for text, images, shapes, slides, and guides.
+ * Used by: GoogleSlidesEditor, export helpers, hooks, and layout utilities.
+ * Depends on: TypeScript only.
+ */
+
 export type ElementType = 'text' | 'image' | 'shape';
 export type ShapeType = 'rectangle' | 'circle' | 'triangle' | 'arrow' | 'star' | 'diamond' | 'hexagon' | 'line';
 

lib/generated-presentation.ts

@@ -1,3 +1,10 @@
+/*
+ * generated-presentation.ts
+ * Purpose: Defines the typed shape of generated presentation responses and helpers for normalizing them into SlideSpec data.
+ * Used by: GoogleSlidesEditor and generation API consumers.
+ * Depends on: SlideSpec types and slide-prompt layout normalization.
+ */
+
 import type { SlideSpec } from '@/data/templates';
 import { normalizeLayout } from '@/lib/slide-prompt';
 

lib/hf-client.ts

@@ -1,3 +1,10 @@
+/*
+ * hf-client.ts
+ * Purpose: Wraps Hugging Face Inference calls behind a small client with provider/model error handling.
+ * Used by: Presentation generation and AI text editing routes.
+ * Depends on: Hugging Face SDK and model configuration helpers.
+ */
+
 import { InferenceClient } from "@huggingface/inference";
 import { LLAMA_PRESENTATION_MODEL } from "./ai-models";
 

lib/layout-templates.ts

@@ -1,3 +1,10 @@
+/*
+ * layout-templates.ts
+ * Purpose: Provides default editor canvas layouts, background helpers, and element factory utilities.
+ * Used by: GoogleSlidesEditor and legacy canvas slide creation paths.
+ * Depends on: Editor theme definitions and editor element types.
+ */
+
 import type { TextElement, ImageElement, EditorElement } from './editor-types';
 import { themes } from './editor-themes';
 

lib/template-options.ts

@@ -1,3 +1,10 @@
+/*
+ * template-options.ts
+ * Purpose: Maps user-facing template picker labels to normalized template IDs.
+ * Used by: HomePage and any code restoring template choices from storage.
+ * Depends on: Template ID conventions.
+ */
+
 export const TEMPLATE_OPTIONS = [
   { id: 'neobrutalism', label: 'Neo-Brutal' },
   { id: 'galeryn', label: 'Galeryn' },

next.config.ts

@@ -1,3 +1,10 @@
+/*
+ * next.config.ts
+ * Purpose: Stores the Next.js build/runtime configuration for the app.
+ * Used by: Next.js build and dev server.
+ * Depends on: Next.js config schema and package transpilation needs.
+ */
+
 import type { NextConfig } from "next";
 
 const nextConfig: NextConfig = {

types/index.ts

@@ -1,3 +1,10 @@
+/*
+ * index.ts
+ * Purpose: Holds shared top-level project types that do not belong to a specific runtime module.
+ * Used by: Any code importing shared project-wide types.
+ * Depends on: TypeScript only.
+ */
+
 // =============================================================================
 // PRESENTATION CONFIGURATION INTERFACES
 // =============================================================================