@morphika/andami 0.5.0 → 0.5.2

package/README.md

@@ -1,26 +1,23 @@
 # @morphika/andami
 
-A reusable Visual Page Builder framework for Next.js. Build custom websites with a drag-and-drop visual editor, Sanity CMS backend, and zero-config deployment.
+**A visual page builder framework for Next.js — the engine behind [morphika.tv](https://morphika.tv).**
 
-**Designed for Vercel Hobby tier** — the framework is engineered to run comfortably within Vercel's free/Hobby plan limits (4h Fluid Active CPU, 10 GB Fast Origin Transfer per month). Aggressive ISR caching, Sanity CDN routing, bot mitigation, and Edge-first middleware keep serverless CPU usage minimal even under crawler traffic.
+Andami is a self-hosted, code-first alternative to Webflow / Framer / Semplice. You scaffold a new site in one command, write your branding in a single config file, and get a Sanity-backed CMS plus a drag-and-drop visual editor — all running on Vercel's free Hobby tier.
 
-## Features
+> **Status — actively maintained, not actively promoted.**
+> Built and used in production by [Morphika Studio](https://morphika.tv). Released as MIT for transparency and as a reference implementation. Issues and PRs are welcome but not guaranteed a response — this is a personal/studio tool first, an open-source project second.
 
-- **Visual Page Builder** — Infinite canvas editor with device previews (desktop, tablet, phone)
-- **6 Content Blocks** — Text, Image, Image Grid, Video, Spacer, Button (added via "+ Add Block" inside columns)
-- **2 Section-level Blocks** — Project Grid (masonry) and Project Carousel (horizontal "keep browsing" at end of project pages). Added via "+ Add Section"
-- **Cover Sections** — Full-viewport hero sections with proportional rows, background media, and drag-to-resize
-- **V2 Grid System** — 12-column CSS grid with push cascade engine and responsive overrides
-- **Custom Sections** — Create reusable sections with per-instance setting overrides
-- **Navigation Builder** — Visual 12-column grid editor with drag & drop
-- **Animation System** — Enter animations, hover effects (CSS + WebGL shaders), page transitions
-- **Asset Management** — Cloudflare R2 storage with browser, thumbnails, and CDN serving
-- **Full Site Backups** — Client-side ZIP export/restore. Browser talks directly to R2 (public CDN + presigned PUT URLs); Vercel only sees lightweight JSON, so backups never hit the 4.5 MB / 10s serverless limits
-- **Setup Wizard** — Guided onboarding for new sites
-- **Sanity v3 CMS** — Structured content with custom schemas, GROQ queries, and ISR
-- **Vercel-Optimized** — Sanity CDN for public queries, 24h ISR, R2 direct CDN shortcut, bot guard middleware, aggressive robots.txt with crawl-delay — all tuned to minimize serverless CPU on Hobby tier
+---
 
-## Quick Start
+## Demo
+
+🔗 **Live site:** [morphika.tv](https://morphika.tv)
+🔗 **Admin preview:** _(add screenshot/GIF here — `docs/media/admin-preview.png`)_
+🔗 **Builder canvas:** _(add screenshot here — `docs/media/builder-canvas.png`)_
+
+---
+
+## Quick start
 
 ```bash
 npx create-andami-site my-site
@@ -29,32 +26,150 @@ npm install
 npm run dev
 ```
 
-Visit `http://localhost:3000/admin` to start building.
+Open `http://localhost:3000/admin` and follow the setup wizard. You'll need:
+
+- A free [Sanity](https://www.sanity.io/) account (CMS backend)
+- A [Cloudflare R2](https://www.cloudflare.com/developer-platform/products/r2/) bucket (asset storage — also free up to 10 GB)
+- A Vercel account for deployment (optional — works anywhere Next.js runs)
+
+Full guide → [docs/QUICK-START.md](docs/QUICK-START.md)
+
+---
+
+## Who this is for
+
+✅ **Designers / studios** who want a polished portfolio site they fully own — no monthly subscription, no platform lock-in.
+✅ **Developers** building bespoke sites for clients in the design / architecture / fashion / photography space.
+✅ **Anyone** who has outgrown Webflow's pricing or wants a Next.js codebase they can extend.
+
+## Who this is *not* for
+
+❌ Non-technical users expecting a SaaS experience. You need to deploy it yourself.
+❌ E-commerce, blogs at scale, or content-heavy sites. Andami is optimized for portfolio / brand / case-study sites.
+❌ Teams looking for guaranteed support or SLAs. This is single-maintainer software.
+
+---
+
+## What's inside
+
+### Visual page builder
+- Infinite canvas with zoom, pan, minimap and device frames (desktop / tablet / phone)
+- Cross-section drag-and-drop between V2 sections, Cover sections, and Parallax groups
+- 12-column responsive grid with push-cascade overlap resolution
+- Per-viewport overrides (desktop / tablet / mobile) for every block
+
+### Content blocks (10)
+- Text (Tiptap rich text with inline color, links, BubbleMenu)
+- Image, Image Grid, Video, Audio, Spacer, Button, Before/After
+- Project Grid (masonry with multi-aspect-ratio cards)
+- Project Carousel (horizontal "keep browsing" at end of project pages)
+
+### Section types
+- **V2 Section** — flat columns, content-driven height
+- **Cover Section** — full-viewport, proportional rows, background media, drag-to-resize
+- **Parallax Group** — multi-slide parallax with crossfade / reveal transitions
+- **Custom Section** — reusable sections with per-instance overrides
+
+### Animation system
+- 7 enter-animation presets + per-character typewriter
+- 4-level cascade (block → column → section → page)
+- Hover effects: 7 CSS presets + 3 WebGL shaders (ripple, RGB shift, pixelate)
+- Page exit animations that replay enter animations in reverse
+
+### CMS & assets
+- Sanity v3 schemas (5 doc types, 10+ object types)
+- Cloudflare R2 storage with presigned uploads, asset registry, thumbnail CLI
+- Full-site backup & restore (client-side ZIP, bypasses serverless body limits)
+- Custom font upload with magic-byte validation
+
+### Vercel-Hobby-tier optimized
+- Sanity CDN routing for public queries (~2ms vs ~200ms)
+- 24h ISR with on-demand revalidation
+- Edge-middleware bot guard (blocks 20+ aggressive crawlers before they hit serverless)
+- Aggressive `robots.txt` with crawl-delay and AI-scraper blocks
+- React `cache()` deduplication on SSR fetches
+
+→ Designed to run a low-traffic portfolio site comfortably within 4h Fluid Active CPU/month.
+
+---
 
 ## Stack
 
-Next.js 16 (App Router) · Sanity v3 · Tailwind CSS v4 · Zustand · @dnd-kit · TypeScript
+| Layer | Choice |
+|---|---|
+| Framework | Next.js 16 (App Router) |
+| CMS backend | Sanity v3 |
+| State | Zustand 5 |
+| Drag & drop | @dnd-kit |
+| Styling | Tailwind CSS v4 |
+| Rich text | Tiptap 2 |
+| Shaders | OGL (WebGL) |
+| Storage | Cloudflare R2 (S3-compatible) |
+| Tests | Vitest + React Testing Library (980+ assertions) |
+
+### Why this stack
+
+- **Next.js + Sanity** — most boring, well-documented stack for content-driven sites. ISR + GROQ scales to any portfolio.
+- **Zustand instead of Redux** — the page-builder state is complex (drag, undo/redo, multi-viewport overrides, snapshots) but a single feature; Zustand's slice pattern keeps it readable.
+- **Sanity for data, not for editing** — Sanity is excellent as a structured-content backend but its built-in studio doesn't fit a visual layout tool. Andami uses Sanity purely as a typed JSON store.
+- **Cloudflare R2 over S3** — zero egress fees. For a portfolio site that's the difference between $0/mo and "depends on the month".
+
+---
+
+## Architecture
+
+Andami ships as an npm package (`@morphika/andami`). Each deployed site is an **instance** — a thin Next.js app that imports framework code and provides its own `site.config.ts`:
+
+```
+my-site/                          # Instance (your repo)
+├── site.config.ts                # Branding, fonts, palette, features
+├── app/
+│   ├── (site)/page.tsx           # → re-exports @morphika/andami/site/page
+│   ├── admin/                    # → re-exports admin pages
+│   └── api/                      # → re-exports API routes
+└── lib/config-init.ts            # Registers config with the framework
+
+@morphika/andami/                 # Framework (this repo)
+├── components/builder/           # Visual editor
+├── components/blocks/            # Public-site renderers
+├── lib/sanity/                   # Schemas, queries, types
+└── app/api/                      # All API routes (auth, pages, assets, R2, backups)
+```
+
+This split lets you upgrade the framework with `npm update` without touching the instance, and lets one studio run many sites from a single shared codebase.
+
+→ Full breakdown in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
+---
 
 ## Documentation
 
-| Doc | Description |
-|-----|-------------|
-| [Quick Start](docs/QUICK-START.md) | 5-minute quickstart |
-| [Configuration](docs/CONFIGURATION.md) | `site.config.ts` reference |
-| [Architecture](docs/ARCHITECTURE.md) | Technical architecture and data flow |
-| [Blocks](docs/BLOCKS.md) | All block types with fields and options |
-| [Builder](docs/BUILDER.md) | Page builder UI, interactions, store |
-| [Canvas](docs/CANVAS.md) | Infinite canvas, zoom/pan, device frames |
+| Doc | What's in it |
+|---|---|
+| [QUICK-START](docs/QUICK-START.md) | 5-minute setup for a new instance |
+| [CONFIGURATION](docs/CONFIGURATION.md) | Every field of `site.config.ts` |
+| [ARCHITECTURE](docs/ARCHITECTURE.md) | Data flow, module boundaries, design decisions |
+| [BUILDER](docs/BUILDER.md) | Visual editor — interactions, store, undo/redo |
+| [CANVAS](docs/CANVAS.md) | Infinite canvas, zoom, pan, device frames |
+| [BLOCKS](docs/BLOCKS.md) | All 10 block types with fields and options |
 | [CMS](docs/CMS.md) | Sanity schemas and GROQ queries |
-| [Navigation](docs/NAVIGATION.md) | Navigation builder, grid editor, styling |
-| [Assets](docs/ASSETS.md) | Storage, providers, thumbnails |
-| [Backups](docs/BACKUPS.md) | Full site backup & restore (V2 client-side architecture) |
-| [Thumbnails](docs/THUMBNAILS.md) | Thumbnail system and CLI tool |
-| [Customization](docs/CUSTOMIZATION.md) | Custom blocks, fonts, styles |
-| [Security](docs/SECURITY.md) | Auth, CSRF, input validation, encryption |
-| [Deployment](docs/DEPLOYMENT.md) | Vercel, domains, R2 setup |
-| [Package Dev](docs/PACKAGE-DEV.md) | Dev workflow, npm link, publishing |
+| [NAVIGATION](docs/NAVIGATION.md) | Navigation builder spec |
+| [ASSETS](docs/ASSETS.md) | Storage, providers, thumbnails |
+| [BACKUPS](docs/BACKUPS.md) | Full-site backup & restore (V2 client-side) |
+| [CUSTOMIZATION](docs/CUSTOMIZATION.md) | Custom blocks, fonts, schemas |
+| [SECURITY](docs/SECURITY.md) | Auth, CSRF, encryption, sanitization |
+| [DEPLOYMENT](docs/DEPLOYMENT.md) | Vercel, domains, R2 setup |
+| [PACKAGE-DEV](docs/PACKAGE-DEV.md) | Local dev, npm link, publishing |
+
+---
 
 ## License
 
-MIT
+[MIT](LICENSE) — use it, fork it, ship clients with it. Attribution appreciated but not required.
+
+---
+
+## Credits
+
+Built by [Daniel Planas](https://morphika.tv) at Morphika Studio.
+The name *Andami* (Catalan for "scaffold") refers to the temporary structures used to build something more permanent.

package/app/admin/assets/page.tsx

@@ -178,7 +178,7 @@ export default function AdminAssetsPage() {
           <button
             onClick={handleScan}
             disabled={scanning}
-            className="font-mono text-[11px] px-3 py-1.5 rounded bg-[#076bff] text-white hover:bg-[#076bff]/80 transition-colors disabled:opacity-50"
+            className="font-mono text-[11px] px-3 py-1.5 rounded bg-[#3580f9] text-white hover:bg-[#3580f9]/80 transition-colors disabled:opacity-50"
           >
             {scanning ? "Scanning..." : "🔄 Scan Storage"}
           </button>
@@ -257,7 +257,7 @@ export default function AdminAssetsPage() {
             setPage(0);
           }}
           placeholder="Search assets..."
-          className="flex-1 rounded border border-neutral-200 bg-white px-3 py-1.5 font-mono text-xs text-neutral-900 focus:border-[#076bff] focus:outline-none shadow-sm"
+          className="flex-1 rounded border border-neutral-200 bg-white px-3 py-1.5 font-mono text-xs text-neutral-900 focus:border-[#3580f9] focus:outline-none shadow-sm"
         />
         <select
           value={statusFilter}
@@ -265,7 +265,7 @@ export default function AdminAssetsPage() {
             setStatusFilter(e.target.value);
             setPage(0);
           }}
-          className="rounded border border-neutral-200 bg-white px-2 py-1.5 font-mono text-xs text-neutral-900 focus:border-[#076bff] focus:outline-none"
+          className="rounded border border-neutral-200 bg-white px-2 py-1.5 font-mono text-xs text-neutral-900 focus:border-[#3580f9] focus:outline-none"
         >
           <option value="all">All statuses</option>
           <option value="active">Active</option>
@@ -279,7 +279,7 @@ export default function AdminAssetsPage() {
             setTypeFilter(e.target.value);
             setPage(0);
           }}
-          className="rounded border border-neutral-200 bg-white px-2 py-1.5 font-mono text-xs text-neutral-900 focus:border-[#076bff] focus:outline-none"
+          className="rounded border border-neutral-200 bg-white px-2 py-1.5 font-mono text-xs text-neutral-900 focus:border-[#3580f9] focus:outline-none"
         >
           <option value="all">All types</option>
           <option value="image">Images</option>
@@ -329,7 +329,7 @@ export default function AdminAssetsPage() {
             }
             className={`w-full grid grid-cols-[1fr_80px_80px_60px_100px] gap-2 px-3 py-2 border-b border-neutral-100 text-left transition-colors ${
               selectedAsset?._key === asset._key
-                ? "bg-[#076bff]/5"
+                ? "bg-[#3580f9]/5"
                 : "hover:bg-neutral-50"
             }`}
           >
@@ -378,7 +378,7 @@ export default function AdminAssetsPage() {
                 onClick={() => setPage(i)}
                 className={`font-mono text-[10px] px-2 py-1 rounded border transition-colors ${
                   page === i
-                    ? "border-[#076bff] bg-[#076bff]/10 text-[#076bff]"
+                    ? "border-[#3580f9] bg-[#3580f9]/10 text-[#3580f9]"
                     : "border-neutral-300 text-neutral-500 hover:text-neutral-900"
                 }`}
               >