themecore

themecore

themecore is the shared Go package of the Umono theme system. The Umono runtime and the Umono CLI embed it, so a theme is checked by the same rules when it is built, installed and activated.

Status: under development for Umono v0.9. The API is not stable yet.

Install

go get github.com/umono-cms/themecore

File Format

All configuration files of the theme system (theme.toml, built.toml, contract.toml and attributes.toml) are TOML v1.0.0 and UTF-8. Syntax added by newer TOML versions is rejected, and so are keys that a schema does not define.

The syntax that TOML v1.1.0 adds is rejected by a scan before decoding, whatever version of the TOML decoder the binary is built with: a newline or a trailing comma in an inline table, the escapes \e and \xHH, and a time or date-time without seconds. A program that builds themecore in calls TOMLConformance in its tests:

func TestTOMLConformance(t *testing.T) {
	if err := themecore.TOMLConformance(); err != nil {
		t.Fatal(err)
	}
}

It returns an error if the decoder accepts a document that is not TOML v1.0.0 or rejects one that is. Go's version selection cannot cap the version of a dependency, so the decoder in a binary may be newer than the one themecore is tested with.

Each file has a schema key. It is required and must be a schema URL that themecore reads for that file, for example https://umono.dev/schemas/theme-manifest/v1 for theme.toml. An unknown URL is rejected, not ignored.

Text fields are single line, without control characters and without leading or trailing whitespace.

Packages

A theme package is read either from a built file (.umono-theme, a zip) or from its installed directory:

p, err := themecore.ReadZip(f, size) // size from the file system's metadata
p, err := themecore.ReadDir("themes/acme/minimal/0.1.0")

Both check the package limits before any file is read, counting the real bytes while reading, and then the package content allowlist.

Hard links are detected by the link count of the file system, which only Unix gives. ReadDir therefore fails on other platforms instead of accepting a package it cannot check; ReadZip works everywhere.

The package root holds only built.toml, contract.toml, checksums.json, attributes.toml and LICENSE, and assets/ is the only directory. Every path segment matches [a-z0-9][a-z0-9._-]* and is at most 64 bytes; LICENSE is the only exception. Empty directories, symlinks, hard links, duplicate or encrypted zip entries and compression methods other than store and deflate are rejected.

assets/theme.css is required and is the only CSS file. Every other file under assets/ has one of these extensions, and its content must start with the format's magic bytes:

Checks

The checks of a package run from one place, in the order of the static check table; CLI and Umono do not call them one by one. CheckPackage is for install and activation:

result, err := themecore.CheckPackage(p) // after VerifyChecksums and the Theme API range

CheckSource is for build and the dev proxy. dir is the development directory and contract the contract file that theme.toml refers to; themecore does not know where the CLI caches it:

p, report, err := themecore.CheckSource(dir, contract)

Only assets/, attributes.toml and LICENSE are read from dir into the package, with contract as contract.toml; theme.toml is checked but does not go in, and other files such as .dev/ and dist/ are not read. An empty directory is skipped, any other file that breaks the package rules stops the build. assets/theme.css is replaced by its canonical CSS. The returned package is what goes into the built file; the CLI adds built.toml with report.Version and then checksums.json. report also holds the evidence of the version and the Lint warnings.

CheckPackage checks that built.toml, contract.toml, checksums.json and assets/theme.css exist, parses built.toml and contract.toml and checks that the contract of built.toml is the package's contract.toml. Then it checks the assets, Verify, the files the CSS URLs point to, attributes.toml against the contract and LICENSE. Last, it rejects a theme-api-version lower than the version of the features the package uses. The Result holds the contract, the compiled attribute table (empty without attributes.toml) and the feature floor with its evidence.

CheckDev is for Umono's dev mode. dir is themes/dev/dev/0.0.0/ and root the theme project (UMONO_THEME_DEV):

result, err := themecore.CheckDev(dir, root) // on every request; nothing is cached

It runs the checks of CheckPackage with the privileges of dev/dev: there is no checksums.json; assets/, attributes.toml and contract.toml may be symlinks that resolve inside root; assets/theme.css goes through Transform instead of Verify; built.toml has the id dev/dev and the version 0.0.0, which ParseBuilt and CheckPackage reject. The package limits and content, built.toml, contract.toml, LICENSE and the feature floor are fatal. Errors of theme.css, attributes.toml and single assets are returned in the result instead, so dev mode goes on: CSSErr, AttributesErr and AssetErrs.

The result also holds Built, the validated built.toml, and ContractSource, the unchanged bytes of contract.toml. Umono checks the Theme API range from Built and adds the contract record from ContractSource instead of reading the files itself: only CheckDev accepts dev/dev and resolves the symlinks inside root. Both are empty on a fatal error.

checksums.json

Checksums returns the content of checksums.json during build; VerifyChecksums checks a package against it during install and activation:

b, err := themecore.Checksums(p) // p without checksums.json
err = themecore.VerifyChecksums(p)

The algorithm is sha256, and files lists every package file except checksums.json itself, with no other entries. Checksums is deterministic: keys in byte order and a fixed format. VerifyChecksums looks at values, not format.

theme.toml

ParseManifest parses and validates theme.toml, the manifest the theme author writes:

m, err := themecore.ParseManifest(b)

Optional keys are nil in Manifest when they are absent.

built.toml

ParseBuilt parses and validates built.toml, the manifest of a package. It has the keys of theme.toml, with the same rules, under the schema https://umono.dev/schemas/theme-built/v1, and two more:

CheckInstallDir checks that the install path themes/{org}/{id}/{version} matches id and version:

b, err := themecore.ParseBuilt(data)
err = b.CheckInstallDir("themes/acme/minimal/0.1.0")

contract.toml

ParseContract parses and validates contract.toml under the schema https://umono.dev/schemas/theme-contract/v1: first the structural layer below, then the sources, which are parsed with Compono (compono.Analyze).

Sources are the only multi-line text fields.

A source with a grammar error that does not depend on values (invalid-expression, unclosed-expression or invalid-parameter-definition), also in a local that is never called, cannot be parsed and is rejected. So is a call or a value that resolves to nothing: not to a local of its source, a component of the contract or a name of Builtins. A default (content = NO_MATTER) only names the type of a parameter and is not checked. A published contract has neither, so the error means that the program is older than the contract. It wraps ErrOutdated, and CLI and Umono report that they are out of date:

if errors.Is(err, themecore.ErrOutdated) {
	// "CLI is out of date" or "Umono is out of date"
}

attributes.toml

CompileAttributes validates attributes.toml under the schema https://umono.dev/schemas/theme-attributes/v1 against the package's contract and compiles it into a table that rendering reads without touching files:

table, err := themecore.CompileAttributes(b, contract)

table.Root("post") // attributes of <umono-root> for the layout post

compono.WithAttributeHook(func(builtin string, chain []compono.Frame) map[string]string {
	return table.Lookup(layout, builtin, chain)
})

• An address is layout, layout BUILTIN or layout COMPONENT BUILTIN, with parts separated by a single space. The layout is a layout of the contract, the component is an exposed one and the built-in is a name of Builtins. A name the contract defines as a component is never a built-in. layout COMPONENT is rejected: an exposed component has no element of its own to write to.
• Only class and sizes are allowed. class is a list of unique printable ASCII tokens separated by single spaces, without the umono- and compono- prefixes (case-insensitive), of at most 1024 bytes. sizes is allowed only on an address that ends with IMAGE and is an HTML source size list without auto. Its media conditions use the media feature vocabulary of the theme CSS, its sizes are lengths in its units or calc(), min(), max() and clamp() of them, and percentages are rejected.
• Lookup finds the scope from the frame chain: the innermost global frame whose scope path is [UMONO_LAYOUT] and whose name is an exposed component, otherwise the layout. A local frame, or a site global with the name of an exposed component, is not a scope. Root and Lookup return a new map on every call, or nil when no address matches.

Theme CSS

Transform turns the theme author's assets/theme.css into the canonical CSS that goes into the package; Verify checks the canonical CSS of a package:

out, err := themecore.Transform(src) // build
err = themecore.Verify(css)          // install and activation

Every style rule of the canonical CSS is inside an @scope (umono-root) block, so the theme cannot style anything outside <umono-root>. Transform parses strictly and never relies on the browser's error recovery; its output always passes Verify. Verify checks the grammar, not the bytes.

The author grammar is closed:

• At-rules: style rules, @media, @supports and @layer blocks; @layer statements, @font-face and @keyframes at the top level only. Every other at-rule, @import and @scope included, is rejected. No nested CSS.
• Selectors: a closed list of pseudo-classes and pseudo-elements. html, body, umono-root, :root, &, id (#id, [id], :target) and namespace prefixes are rejected. <umono-root> itself is styled with :scope in the first compound selector, e.g. :scope.layout-post h1.
• @media: the media types all, screen, print and a closed list of media features.
• Values: a closed list of value functions (env(), if(), sibling-index() and others are rejected); attr() cannot read id; behavior and -moz-binding are rejected.
• Reserved names: umono- and compono- (and --umono-, --compono-) are reserved for Umono.
• URLs are relative paths to allowed files under assets/, e.g. url(fonts/inter.woff2).
• Generated text: content, quotes, list-style-type and list-style cannot generate words. content with a string or an image needs alternative text: content: "→" / "";.

FallbackSource returns the fallback theme, the default look of pages without an active theme, in the author grammar; FallbackCSS returns its canonical CSS. FallbackSource is also the starting assets/theme.css of a new theme.

Lint returns warnings for CSS that is valid but never matches, for development tools only. It reports root classes used without :scope: a class given only to layout addresses in attributes.toml is only on <umono-root>, so .layout-post h1 never matches; write :scope.layout-post h1. It also reports addresses whose component the layout never renders: post-list MAIN_MENU LINK never matches when MAIN_MENU cannot be reached from the source of post-list through calls, values and defaults of the contract sources.

Theme API

The capability ledger (Features and Breaks) is the single source of the Theme API versions. Rows are only appended.

themecore.ThemeAPICurrent() // newest Theme API version
themecore.ThemeAPIMin()     // oldest Theme API version still accepted

DetectThemeAPIVersion returns the version a package declares in built.toml during build, with the evidence for it. DetectFeatureFloor returns the largest version of the features a package uses; install and activation reject a package whose declared version is lower.

version, evidence, err := themecore.DetectThemeAPIVersion(p)
floor, evidence, err := themecore.DetectFeatureFloor(p)

Each Signal names a feature, the version that introduced it and the first place in the package that shows it.

The built-ins and Markdown elements open to themes are rows too (compono.builtin.*, compono.markdown.*), and the sets derive from them:

themecore.Builtins()         // "LINK", "IMAGE", "NAV", …
themecore.MarkdownElements() // "heading", "p", "br", …

Address validation, the detectors and the undefined call rule look only at these sets, not at Compono's lists, so a built-in Compono adds stays closed to themes until its row is added. A built-in detector looks for a reference in contract.toml that resolves to the built-in (a call, a value or a default) and for an address of attributes.toml whose type filter is it. A name the contract defines as a component, in [[components]] or as a local, is never a built-in. A Markdown detector looks for the element in contract.toml. The place of a signal in contract.toml is the key of the source and the line in it, such as contract.toml:layouts[0].source:4.

The detectors that read contract.toml depend on how Compono parses it. themecore embeds a detector corpus (detectorcorpus/: contract inputs and the signals each must give), and a program that builds themecore in runs it in its tests, with the Compono version it is built with:

func TestDetectorCorpus(t *testing.T) {
	if err := themecore.DetectorCorpus(); err != nil {
		t.Fatal(err)
	}
}

License

MIT