BLOKZA — Marketing Site + Visual Editor

Two things live in this repository:

1. The marketing site — pure HTML, CSS and vanilla JavaScript at the repo root. No build step, no dependencies.
2. The builder — a React + TypeScript single-page app in builder/, compiled into app/ and served at /app/.

Pages

Page	Path	Description
Home	index.html	Hero, problem, tabbed showcase, features, templates, pricing, testimonials, FAQ, CTA
Product	product.html	Editor walkthrough
Features	features.html	Full feature matrix
Templates	templates.html	9 production templates
Pricing	pricing.html	Plans, comparison table, monthly/yearly toggle
Docs	docs.html	Sticky sidebar + content
Blog	blog.html	6-post grid with custom SVG covers
Contact	contact.html	Form posting to /api/contact
Builder	app/	The visual builder (built from builder/)
Editor (legacy)	editor.html	301 redirect to /app/ for old links
404	404.html	Branded not-found page

The builder

The builder is a real editor, not a demo: nested containers, per-breakpoint styling, multiple pages, and a static-site export.

Running it

cd builder
npm install
npm run dev        # http://localhost:5273

cd builder
npm test           # unit tests (core model, store, export)
npm run typecheck  # tsc, no emit
npm run build      # typecheck + emit into ../app

app/ is committed, because the marketing site is deployed as static files with no build step. Rebuild it and commit the result whenever builder/ changes.

How it is put together

Area	Where	What it does
Document model	builder/src/core/	Normalised node map, tree queries, drop validation, CSS compiler, storage, export
Components	builder/src/registry/	Layout, content, media and form primitives, plus section templates
State	builder/src/store/editor.ts	Zustand + Immer, snapshot undo with coalescing
Canvas	builder/src/canvas/	Device iframe, pointer drag engine, selection overlay
Panels	builder/src/ui/	Rail, top bar, insert/layers/pages/theme/settings, inspector

Three decisions explain most of the design:

• The canvas is a real <iframe> sized to the device. Media queries fire because the frame genuinely is 390px wide, vh resolves against a real viewport, and no editor CSS can leak into the page.
• Styles compile to a stylesheet, not inline styles. @media and :hover cannot be expressed inline, so responsive and interaction states would otherwise be fake. Properties come from a closed whitelist and every value is validated before it is emitted.
• Templates expand into primitives. A "hero" is a Section holding a Container holding a Row — every part of it selects, restyles and comes apart, rather than being an opaque block with a fixed set of fields.

Export

Publish produces a ZIP containing one HTML file per page, a single styles.css, sitemap.xml and robots.txt. Pages are rendered through the same components the canvas uses, so the output cannot drift from the preview. Links between pages are rewritten to relative filenames, which means the ZIP works from a local folder, an S3 bucket, GitHub Pages or Netlify without changes.

Everything is client-side: work autosaves to localStorage, and the project can be downloaded as a .blokza.json file to move between browsers.

Production checklist

• Semantic HTML5, <main id="main"> landmark per page
• Skip-to-content link on every page
• Focus-visible rings on every interactive element
• Honors prefers-reduced-motion
• Responsive across phone, tablet, desktop
• Open Graph + Twitter card tags per page
• JSON-LD Organization + SoftwareApplication structured data
• Canonical URL per page
• Web App Manifest (/site.webmanifest)
• robots.txt + sitemap.xml
• Custom 404 page
• Security headers (CSP-friendly, HSTS, X-Frame-Options) via vercel.json
• Cache-Control: 1-year immutable on /assets/*, no-cache on HTML, content-hashed ?v= stamps
• Deferred JS, font preconnect
• Contact form delivered by our own SMTP endpoint, honeypot, validation, success/error states
• GitHub Actions CI (HTML/JS validation, broken link check, builder typecheck + tests + build)
• No external runtime dependencies on the marketing site

Deploy

Vercel serves the repository as committed — no build step on their side — and runs api/auth.mjs for /api/auth/*.

./scripts/preflight.sh      # is everything configured?
./scripts/release.sh        # build the editor, regenerate the sitemap, stamp assets
git commit -am "…" && git push

release.sh matters because there is no build on the far side: it is what keeps the committed app/ bundle, sitemap.xml, and every content-hashed ?v= stamp honest. ./scripts/release.sh --check verifies without writing.

Full detail in docs/DEPLOY.md; accounts and sign-in in docs/CLOUD.md.

Wiring the contact form

The form posts to /api/contact, a function in this repository that speaks SMTP and delivers the message as email. Nothing goes through a third-party form service, so submissions are not stored anywhere but the destination inbox.

It needs a mailbox to send from. In the Vercel project's environment variables:

Variable	Required	Meaning
SMTP_USER	yes	The full mailbox — [email protected]
SMTP_PASS	yes	An app-specific password, not the account password
CONTACT_TO	no	Where submissions land; defaults to SMTP_USER
SMTP_HOST	no	Defaults to smtp.zoho.com
SMTP_PORT	no	Defaults to 465 (implicit TLS)

Zoho's free tier has no SMTP — it is web-only for new accounts — so this needs Mail Lite or above. Generate the app password under Zoho's Security → App passwords, never the login password.

With the variables unset the endpoint answers 503 and the form shows its fallback ("email us instead") rather than failing silently. The honeypot, validation, and success/error states are wired up either way.

Local development

No build step. Open index.html directly in a browser, or:

python3 -m http.server 8000
# or
npx serve .

Then visit http://localhost:8000.

Project structure

.
├── index.html / product.html / pricing.html / ...        ← marketing pages
├── editor.html                                           ← redirect to /app/
├── 404.html                                              ← branded not-found
├── sitemap.xml / robots.txt / site.webmanifest           ← SEO foundation
├── vercel.json                                           ← headers, redirects, function region
├── api/auth.mjs                                  ← Neon Auth proxy (first-party cookie)
├── neon/schema.sql                                       ← sites table + row-level security
├── .github/workflows/ci.yml                              ← validation pipeline
├── assets/
│   ├── css/
│   │   ├── base.css     ← tokens, nav, footer, motion utilities
│   │   ├── pages.css    ← hero, features, pricing, testimonials, FAQ
│   │   └── demos.css    ← template demo pages
│   ├── js/
│   │   └── site.js      ← reveals, submenus, pricing toggle, contact form
│   └── og-image.png     ← social share card (1200×630; SVG is not rendered by any platform)
├── app/                                                  ← built builder (committed)
├── builder/                                              ← builder source
│   ├── src/core/        ← document model, CSS compiler, export
│   ├── src/registry/    ← components + section templates
│   ├── src/store/       ← editor state, undo/redo
│   ├── src/canvas/      ← device iframe, drag engine, overlay
│   ├── src/ui/          ← chrome, panels, inspector
│   └── test/            ← unit tests
└── README.md

What the builder can do

Structure. Sections, containers, stacks, rows, grids and cards nest to any depth. Drop anywhere — between siblings, inside a container, into an empty box — with a live indicator showing exactly where an element will land. Drag from the palette, from the canvas, or from the layers tree.

Elements. Heading, text, rich text, button, link, badge, quote, list, icon, image, video, embed, form, input, text area, select, checkbox, submit — plus 14 section templates (nav bar, two heroes, feature grid and media, logo strip, stats, testimonials, pricing, FAQ, gallery, CTA, contact, footer).

Styling. A generic CSS inspector over a whitelisted property set: layout, visual spacing box, size, typography, background, border, effects, position. Every property can be overridden per breakpoint (desktop / tablet / mobile) and for :hover, with the current layer always named in the panel and an indicator on any property you have changed.

Pages and theme. Multiple pages with their own path and SEO metadata, internal links that resolve to real files on export, and design tokens for colour, type, radius and content width.

Editing. Click to select, click again to edit text in place, drag to move, ⌘D to duplicate, ⌘C/⌘V to copy, ⌥↑/⌥↓ to reorder, ⇧↑ to select the parent, and undo across everything — typing counts as one step, not one per keystroke.