# Untilus Portfolio Ultra-premium editorial/type-led designer portfolio with filterable case studies, image reveal/lightbox interactions, before/after comparisons, and GenMB-backed admin project management. ## Masterplan - Present Untilus as a timeless editorial design practice: oversized typography, archive/memory language, dark-first visual system, and image-led case studies. - Serve prospective clients browsing work across **Brand Identity**, **Illustration**, **Web Design**, and **Posters** with URL-shareable filtering. - Let the owner maintain portfolio entries from `#/admin` using GenMB Auth, PostgreSQL projects data, and GenMB File Storage artwork uploads. - Keep the app deployable as a static no-build SPA using CDN React, HTM templates, Tailwind CDN, and browser-native Web Components. - Optimize image-heavy portfolio browsing with aspect-ratio containers, lazy loading, async decoding, and IntersectionObserver-based reveal. ## Tech Stack & Architecture - **Runtime:** Static single-page app from `index.html`; no bundler/transpiler. - **React:** `react@19.2.0` and `react-dom@19.2.0/client` via `https://esm.sh`. - **Templating:** No JSX compilation. Every component uses `html` from `src/jsx.js`, which binds `htm@3.1.1` to React `createElement`. - **Routing:** `HashRouter` from `react-router-dom@7`; public URLs are hash routes like `#/work`, `#/work/:slug`, `#/admin`. - **State:** Zustand in `src/store/useAppStore.js`. - Global state: `theme`, `projects`, `isLoaded`, `activeLightbox`. - Store methods wrap all database calls and global lightbox actions. - **Styling:** Tailwind CDN configured in `index.html` plus HSL tokens, editorial utilities, and animations in `styles/main.css`. - **Icons:** `lucide-react` via esm.sh. - **Fonts:** Google Fonts: - `Cinzel` for serif editorial display/logo/case headings. - `Plus Jakarta Sans` for UI/body/navigation. - **Notifications:** Lightweight toast context in `src/mainProviders.js`. - **GenMB integrations:** - `window.genmb.auth` is injected in `index.html` and consumed directly by `src/pages/Admin.js`. - `window.genmb.db.projects` is wrapped by `src/services/db.js`; do not call the DB directly elsewhere. - `` is used in `src/pages/Admin.js` for hero/gallery uploads. - `` is conditionally used in `src/components/LazyImage.js` for GenMB-like storage URLs. ### File Connections `src/main.js` mounts `` into `#root`. `src/App.js`: - initializes dark theme through `useAppStore().initTheme()`; - defines hash routes; - renders `Header`, `Footer`, page content, and app-wide `Lightbox`; - uses `ScrollToTop` on route pathname changes. All public portfolio pages load project data through `useAppStore.loadProjects()`. Admin mutations call `addProject`, `updateProject`, and `deleteProject`, which delegate to `src/services/db.js`. ## File Structure ```txt index.html Static shell; Tailwind/font config; GenMB Auth capability injection; #root. styles/main.css Dark/light HSL tokens, editorial typography helpers, reveal and toast animations. src/main.js React root bootstrap with Providers and App. src/mainProviders.js Toast context/provider and fixed bottom-right toast stack. src/jsx.js HTM helper; required for all component templates. src/App.js HashRouter routes, scroll restoration, global Header/Footer/Lightbox. src/store/useAppStore.js Zustand state for theme, projects, CRUD wrappers, lightbox. src/services/db.js GenMB projects table abstraction, seed/list/create/update/delete behavior. src/components/Header.js Sticky editorial nav, active route state, theme toggle, Admin link. src/components/Footer.js Studio footer with tagline, directory links, contact/social placeholders. src/components/LazyImage.js IntersectionObserver reveal image wrapper; supports img and genmb-image. src/components/Lightbox.js Fullscreen image viewer with Esc/arrows/buttons/swipe. src/components/BeforeAfterSlider.js Click/drag/touch comparison slider for case-study process/final images. src/pages/Home.js Oversized hero and selected work presentation. src/pages/WorkIndex.js Archive grid with URL-synced ?category= filtering. src/pages/CaseStudyDetail.js Project detail narrative, gallery, quote/process sections, before/after block. src/pages/About.js Bio, skills grid, and collaborator logo strip. src/pages/Contact.js Client inquiry/brief entry page. src/pages/Admin.js GenMB-authenticated admin UI for sign-in, uploads, and project CRUD. ``` ## Key Features ### Public Portfolio - **Home `#/`** - Editorial hero using the Untilus tagline: “Built on memories. Made for forever.” - Selected work area sourced from the global `projects` store. - **Work Index `#/work`** - Displays case-study cards for seeded/admin-created projects. - Category filter must support: `All`, `Brand Identity`, `Illustration`, `Web Design`, `Posters`. - Filter state is synced to `?category=` so filtered archive views are shareable/bookmarkable. - **Case Study Detail `#/work/:slug`** - Looks up a project by slug from store data. - Uses large image blocks with `LazyImage`. - Includes editorial sections for problem/process/solution-style narrative. - Includes `BeforeAfterSlider` for visual comparison. Slider supports click, mouse drag while pressed, and touch move. - Gallery images open the global `Lightbox`. - **About `src/pages/About.js`** - Static studio biography, skills, and collaborator cards. - **Contact `src/pages/Contact.js`** - Public inquiry/brief page; no backend form API is documented in the visible code. ### Image Reveal and Lightbox - `LazyImage.js` uses `IntersectionObserver` with `{ threshold: 0.05, rootMargin: '100px' }`. - Images only render after intersection. - Standard images use: - `loading="lazy"` - `decoding="async"` - parent `aspectRatio` style to avoid CLS. - GenMB/storage-like URLs render with ``. - `Lightbox.js` receives `{ images, index }` from `useAppStore.activeLightbox`. - Close: Esc key or close button. - Navigate: ArrowLeft/ArrowRight, buttons, or horizontal swipe over 50px. - Index wraps around at both ends. ### Admin CRM / Project Management - Route: `#/admin`. - Auth is handled in `src/pages/Admin.js` using `window.genmb.auth`. - Supported auth modes in current code: - Google popup/redirect sign-in. - Magic link. - Email/password sign-in. - Signup with OTP verification. - Password reset with OTP. - Sign out. - Uploads: - Hero uploader ref updates `form.hero_image_url`. - Gallery uploader ref appends uploaded file URLs to `form.gallery_urls`. - Upload completion event listened for: `genmb-upload-complete`. - Expected event shape: `e.detail.files`, with each file containing `url`. - Project form fields currently managed in Admin: - `title` - `category` - `client` - `year` - `description` - `hero_image_url` - `gallery_urls` - `display_order` - Admin page loads projects on mount even before/while auth is resolving. Keep data reads resilient. ### Data Model Canonical project table fields from the product prompt and DB wrapper: ```js { id, title, slug, category, // Brand Identity | Illustration | Web Design | Posters client, year, description, // markdown/plain editorial copy hero_image_url, gallery_urls, // JSON/array of image URLs display_order, published_at } ``` Seed content must include 8 placeholder works using these exact Picsum URLs: ```txt https://picsum.photos/seed/design-brand-1/1400/1000 https://picsum.photos/seed/design-brand-2/1400/1000 https://picsum.photos/seed/design-illust-1/1400/1000 https://picsum.photos/seed/design-illust-2/1400/1000 https://picsum.photos/seed/design-poster-1/1000/1400 https://picsum.photos/seed/design-poster-2/1000/1400 https://picsum.photos/seed/design-web-1/1600/1000 https://picsum.photos/seed/design-web-2/1600/1000 ``` ## Design Guidelines - **Default theme:** dark. `initTheme()` always adds `dark` to `document.documentElement`; no persistence is currently implemented. - **Theme tokens:** use HSL CSS variables from `styles/main.css`: - `--background`, `--foreground`, `--primary`, `--secondary`, `--muted`, `--border`, `--card`, `--destructive`. - **Light mode:** toggled by adding/removing `.dark` class through the store, though token overrides are defined under `.light`. If changing theme mechanics, align Tailwind `darkMode: 'class'`, store state, and CSS selectors carefully. - **Typography:** - Use `font-serif`/Cinzel for logo, major editorial headings, pull quotes. - Use `font-sans`/Plus Jakarta Sans for navigation, body text, controls. - `styles/main.css` provides `.editorial-title` and `.editorial-subtitle` for oversized responsive type. - **Layout:** - Main horizontal padding pattern: `px-6 md:px-12`. - Max width pattern: `max-w-7xl mx-auto`. - Use generous spacing (`space-y-24`, `gap-12`) to preserve editorial feel. - **Controls:** mobile tap targets should remain at least 44x44px; header theme buttons and lightbox controls already follow this. - **Image presentation:** always wrap image grids/cards in fixed `aspectRatio` containers and use object-cover/object-contain intentionally. ## App Flow - **Visitor browsing selected work** 1. Enters `#/`. 2. `App` initializes theme and renders `Home`. 3. Home loads projects via store if not already loaded. 4. Visitor opens work cards to `#/work/:slug`. - **Visitor filtering archive** 1. Opens `#/work`. 2. Chooses category filter. 3. Page updates the displayed cards and the URL `?category=`. 4. Empty or unknown category should not crash; fall back to all or no-results UI depending current page logic. - **Visitor viewing case study** 1. Opens `#/work/:slug`. 2. Detail page resolves project by slug. 3. Lazy images reveal on scroll. 4. Gallery click calls `openLightbox(images, index)`. 5. Lightbox closes with Esc or close button; navigation wraps. - **Owner editing portfolio** 1. Opens `#/admin`. 2. `Admin.js` waits for `window.genmb.auth.ready()`. 3. If unauthenticated, owner chooses Google, magic link, password, signup, or reset flow. 4. Once authenticated, owner creates/edits/deletes projects and uploads artwork. 5. Store updates local `projects` state after DB mutations. ## Conventions - **Component syntax:** use HTM tagged templates only: ```js return html`

${value}

`; ``` Do not introduce raw JSX unless a build step is added. - **Imports:** continue using esm.sh CDN imports with React version pinned to `19.2.0`. - **Data access:** only `src/services/db.js` should know GenMB DB details. Pages/components should use `useAppStore`. - **Global UI state:** add cross-page UI state to `src/store/useAppStore.js`; keep page-local form/auth state inside the relevant page. - **Project mutations:** after `dbService` returns, update the Zustand array immediately so the UI reflects changes without a full reload. - **Lightbox pattern:** call `openLightbox(imageArray, clickedIndex)` from pages/components; do not mount separate page-level lightboxes. - **Image pattern:** prefer `LazyImage` for portfolio imagery. Use direct `` only for simple fixed UI or inside `Lightbox`/`BeforeAfterSlider`. - **Adding a page:** 1. Create `src/pages/NewPage.js`. 2. Export a named component. 3. Import it in `src/App.js`. 4. Add a `` under `Routes`. 5. Add nav/footer links only if it is part of the public directory. - **Adding a portfolio feature:** extend `dbService` first, add store action second, then update pages. Avoid direct `window.genmb.db.projects` usage in page components. - **Gotcha:** `Admin.js` uses native Web Component event listeners through refs. If uploader markup changes, keep `genmb-upload-complete` listener setup/cleanup in sync and verify `e.detail.files[].url`. - **Gotcha:** theme CSS currently defines `.light` variables while Tailwind dark mode relies on `.dark`. Be careful when modifying theme toggling so CSS variables and Tailwind variants do not drift. ## 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.