Modules

Building a Web theme

Writing themes for Blesyum Web: package layout, validator, CLI, and the CSP limits of visitor pages.

A Blesyum Web theme renders the visitor-facing side of a site. A package is a ZIP; every file in it is validated before upload.

Fast loop

bash
blesyum-tema init my-theme       # copy the starter theme
blesyum-tema validate my-theme   # validate (exit code 1 on errors)
blesyum-tema watch my-theme      # re-validate on change
blesyum-tema build my-theme -o theme.zip

The validator is byte-for-byte the server's: the CLI does not write its own rules. A package that passes locally passes on upload.

Package layout

text
theme.json          # manifest: name · version · min_engine
templates/          # page skeletons (Liquid)
blocks/<name>/block.json + <name>.liquid
assets/css/…
assets/img/…
locales/en.json
  • Unknown manifest fields are kept, not stripped (forward compatibility).
  • block.json's name must match its directory: if they diverge the editor lists the block under one name and the engine looks for another, and the block is silently not rendered.
  • A min_engine mismatch blocks the upload and the reason is given as a number. Major differences are closed in both directions.
  • Versions must be full semver: &quot;1.2&quot; is not 1.2.0.

🔴 JavaScript does not run on visitor pages

This is not a missing feature — it is the architecture. Visitor pages are served under a CSP with no script-src and no frame-src; img-src is &#39;self&#39; data: and form-action is &#39;self&#39;.

  • Don't ship &lt;script&gt;. It fails silently in the browser: curl shows correct HTML, the endpoint returns 200, logs are clean, and the failure is visible only on the visitor's screen. The validator reports it as an upload-time error.
  • Don't embed &lt;iframe&gt;. The box renders empty. Use a link instead — a link is not subject to CSP (CSP restricts resource loading, not navigation).
  • Don't pull images or fonts from a CDN. Put assets in assets/.
  • Don't submit forms with fetch. Use a plain POST.

Why: theme code is written by the tenant or their agency, and the panel lives on a separate origin (&lt;slug&gt;--panel.web.&lt;domain&gt;). Theme JS on the same origin could read the panel's session token, and no CSP could stop that.

What the validator checks

Syntax · CSP (&lt;script&gt;, external img/font, &lt;iframe&gt;) · accessibility (missing alt, heading order) · performance (unsized images, oversized assets) · locales (a missing translation is a warning, not an error — the last link of the chain is the source string).

Uploads and versions

Every upload is a separate record; the same name + version cannot be installed twice. Uploading is not activation: repainting a live site without asking would apply a decision the customer never made. Activation is a separate step and produces a compatibility report (blocks with no counterpart, migrated settings).

Rolling back needs no separate mechanism: the previous version's record is still there and can be activated. The site's theme history shows which one is live.