BLOKZA — Marketing Site + Visual Editor
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/.
The builder is a real editor, not a demo: nested containers, per-breakpoint
styling, multiple pages, and a static-site export.
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.
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
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.
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:
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:
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.
