ZeroPress Theme Runtime Spec v0.2

Status: Superseded by v0.3

This document is kept for historical reference only.
New validation, upload, and submission flows must use v0.3:
Theme Runtime v0.3

0. Core Philosophy

Themes define structure, not application behavior.
A theme bundle is a file-only artifact.
Tooling (dev, validate, pack) is external to the runtime contract.
Themes must render meaningful HTML even without JavaScript.

1. Scope

A ZeroPress theme is responsible only for:

HTML templates
CSS and static assets
Theme metadata (theme.json)

Out of scope:

Backend APIs, authentication, and admin features
Client-side routing-dependent app architecture
Runtime logic-centric application behavior

2. Runtime Contract

Baseline structure compatible with current build/upload pipelines:

my-theme/
  theme.json
  layout.html
  index.html
  post.html
  page.html
  archive.html
  category.html
  tag.html
  404.html (optional)
  partials/
    *.html
  assets/
    style.css
    theme.js (optional)

Key points:

Template files are expected as root-level .html files.
partials/ is optional.
assets/style.css is required.
assets/theme.js is optional and is not auto-executed by the runtime contract.
archive.html, category.html, and tag.html are optional capabilities. If a theme omits them, related route outputs are omitted even when preview-data still contains those route arrays.
404.html is optional. When present, build tooling may emit a 404.html artifact; when absent, that artifact is omitted.
Upload ZIPs may be root-flat or wrapped in one top-level folder.

3. `theme.json` v0.2

Minimal example:

{
  "name": "My Theme",
  "namespace": "your-namespace",
  "slug": "my-theme",
  "version": "0.2.0",
  "license": "MIT",
  "description": "A ZeroPress theme.",
  "runtime": "0.2"
}

Required fields:

name (string, 1-80 chars)
namespace (string, 3-24 chars)
slug (string, 3-32 chars)
version (semver)
license (enum)
runtime (must be "0.2")

Optional fields:

author (string, 1-80 chars if present)
description (string, up to 280 chars)

License enum:

MIT
Apache-2.0
BSD-3-Clause
GPL-3.0-only
GPL-3.0-or-later

Identity rules:

namespace and slug must follow the ZeroPress package naming rules
namespace must match the registered publisher namespace in directory-backed submission flows
slug is the canonical theme identifier within a namespace

4. Template Rules

layout.html must include exactly one {{slot:content}}.
Allowed slot names: content, header, footer, meta.
Nested slot expressions are not allowed.
<script> tags are not allowed in layout.html.
Mustache block syntax is not allowed ({{#...}}, {{/...}}).

5. Variables and Rendering

Only simple variable substitution is supported.
Rendering is designed for build-generated data injection.
JavaScript is for progressive enhancement, not core rendering.
Preview-data stays canonical and data-only; build tooling computes theme-facing render data immediately before template rendering.
Runtime data may include richer HTML-ready fields on post objects.
{{post.comments_html}} is supported as an optional rendered HTML fragment for post comment sections.

6. Security and Packaging Rules

Tooling does not execute theme code.
Path escape is forbidden.
Symlink-based root escape is forbidden.
Distribution unit is a ZIP archive.

Commonly excluded files:

.git
node_modules
dist
*.log
__MACOSX, .DS_Store
package-lock.json, pnpm-lock.yaml, yarn.lock, bun.lockb

7. Validation Profile

Errors:

Missing theme.json or invalid JSON
Missing required templates (layout.html, index.html, post.html, page.html)
Missing assets/style.css
Missing required manifest fields
Invalid version semver
Invalid license
runtime not equal to "0.2"
Invalid namespace or slug
layout.html slot rule violations
Disallowed template syntax patterns

Warnings:

Missing optional templates: archive.html, category.html, tag.html
post.html missing {{post.comments_html}}
{{post.comments_html}} used outside post.html

Runtime behavior:

Required preview-data route arrays do not guarantee emitted artifacts for optional route kinds.
archive, category, and tag pages are emitted only when both renderable route data exists and the matching template exists.
404.html is emitted only when the theme provides a 404.html template.

8. CLI Alignment

npx zeropress-theme validate, pack, and dev use this runtime contract as the baseline.

9. Compatibility Notes

v0.2 is kept for historical reference only.
New validation and upload flows must use v0.3.

10. Toolkit Baseline

Node.js: >= 18.18.0
ESM only
CommonJS is not supported

11. Normative vs Informative Summary

Item	Classification	Notes
`theme.json`, `layout.html`, `index.html`, `post.html`, `page.html`, `assets/style.css`	Normative (Required)	Missing files produce validation errors
`theme.json.name`, `theme.json.namespace`, `theme.json.slug`, `theme.json.version`, `theme.json.license`, `theme.json.runtime`	Normative (Required)	Must be present and valid
`theme.json.author`	Informative (Optional)	Optional package display metadata
`theme.json.description`	Informative (Optional)	Recommended metadata for theme clarity
`layout.html` must contain exactly one `{{slot:content}}`	Normative (Required)	Validation error if violated
Allowed slots: `content`, `header`, `footer`, `meta`	Normative (Required)	Unknown slots are invalid
No `<script>` in `layout.html`	Normative (Required)	Validation error
Mustache block syntax forbidden (`{{#...}}`, `{{/...}}`)	Normative (Required)	Validation error
Path/symlink root escape forbidden	Normative (Required)	Validation error
`archive.html`, `category.html`, `tag.html`	Informative (Recommended)	Missing files produce warnings
`partials/` directory	Informative (Optional)	Supported but not required
`assets/theme.js`	Informative (Optional)	Optional file; not auto-executed