khosra/harness/theme-contract.md

Theme contract

What the engine promises a theme, and the only thing this repository is bound to (ADR-0023). A theme's markup, layout and styling are not the engine's business; a theme's inputs are.

STATUS: partly live. The fields under Live today exist and are gated; everything else is the shape the contract takes when the feature arrives. All of it is engine obligation, not theme instruction — a theme may ignore any of it.

Live today

A bundle page receives:

Field	Contents
.Title	may be empty; a template falls back to .Key rather than failing
.Lang	the locale of this variant, always set
.Key	the bundle's identity, without language or extension. Not its address — a slug moves the address and leaves the key alone, so link with .URL or .Canonical and never by assembling a key (ADR-0035)
.HTML	the rendered body, already escaped
.Extra	every frontmatter key the parser does not name (ADR-0002)
.Style	the reference theme's stylesheet, inlined so a bare site root needs no asset route
.Canonical	the permalink of the variant actually served — not the URL requested, which differs when the fallback chain supplied another language. Absolute when the site declares base, since a canonical link is resolved by machines rather than by the page (ADR-0039)
.Alternates	every language this key exists in: .Lang, .URL (absolute, for hreflang) and .Path (root-relative, for a visible language link — .URL would send a reader to the canonical host)
.Site	what the site declared about itself: .Site.Base and .Site.Title, either possibly empty
.Sections	every section that holds something, for navigation. Only .Title and .URL are set, and the list is empty on a bare site (ADR-0049)
.Sequence	the series this page sits in, absent when it sits in none (ADR-0033)
.Tags	this bundle's own terms, each with the URL of its listing; empty when it carries none (ADR-0049)
.ExtrasURL	this bundle's supporting files, empty when it has none — so a theme can offer them without guessing (ADR-0047)

.Sequence carries the reading order and this page's place in it:

Field	Contents
.Sequence.Title, .Sequence.URL	the series' title (may be empty) and its permalink
.Sequence.Members	every entry in reading order, each as an .Items entry — ascending, unlike a dated listing
.Sequence.Index, .Sequence.Count	this page's 1-based position and the total; Index is 0 when this page is the series landing itself
.Sequence.Prev, .Sequence.Next	the neighbours, absent at the ends and on a landing page. Prev is the earlier entry — the opposite sense of a listing's .PrevURL
.Sequence.First, .Sequence.Last	the ends of the series, present whenever it has members

A landing page therefore renders an archive from .Members and a chapter renders navigation from .Prev/.Next, both from one field. Membership and order are the engine's business (content-model.md); a theme never sorts.

Two named templates: base is executed for every page; main is the block each kind of page defines and a theme redefines. There is one parsed set per kind — bundle and listing today — so two kinds may both define main without colliding (ADR-0019).

Every kind of page receives .Title, .Lang, .Canonical, .Style, .Site, .Sections and .Alternates — the document shell. A listing page adds:

Field	Contents
.Items	entries on this page: .Title, .Key, .URL, .Date, .Section
.Page, .Pages	1-based position and total, Pages at least 1
.PrevURL, .NextURL	empty at the ends; newer is prev, because the order is newest first
.Groups	the same entries partitioned by section, each with .Name and .Items. A tag listing supplies both shapes and the theme picks: templates cannot group, so the engine offers the partition, but whether a listing looks grouped is markup (ADR-0046)

Chrome text and formatting

Three functions, available in every template including a site root's own blocks. They exist so no template hardcodes English: the words the engine supplies are the engine's to localise (ADR-0034).

Call	Gives
{{t .Lang "newer"}}	one phrase in that language. Extra arguments fill %s placeholders in order
{{num .Lang .Page}}	an integer in that language's digits — 12, ১২
{{day .Lang .Date}}	a date as that language reads it — 8 March 2026, ৮ মার্চ ২০২৬; empty for a zero date

Phrase keys today: newer, older, empty, page-of (two arguments), position (two arguments), first, last, extras, back-to-page, contents, note, warn, tip, details. An unknown language falls back to the default locale and an unknown key returns itself, so a missing translation can never blank a page or fail a render.

Three rules a theme must keep: put the machine-readable form in the attribute and the localised form in the text — <time datetime="{{.Date.Format "2006-01-02"}}">{{day .Lang .Date}}</time>; never localise .Title, .HTML or anything else the author wrote; and never pass a URL, key or path segment through these functions. An address is not chrome (content-model.md).

A site root cannot add or override a phrase yet. A theme needing its own words writes them in its own block; site-supplied strings wait for the settings cascade (ideas/deferred-decisions.md).

Shortcode fragments

Fragments live in templates/shortcodes.html, or in templates/shortcodes/*.html, or both — one named template per shortcode, and that is where a shortcode's markup lives. The engine parses the call and supplies its data, never any HTML (ADR-0036).

Parse order is embedded file, embedded directory, site file, site directory, and the last definition of a name wins (ADR-0071). So the directory overrides the file within one source, and a site overrides the binary either way. The reference theme ships the directory: figure, gallery, icon, admonitions (note, warn, tip), details, aside, toc. Override one by defining that name anywhere the engine looks; everything you leave alone is inherited.

Assets a fragment needs

A shortcode that needs CSS or JS declares it as a second fragment named assets:<name> (ADR-0079):

{{define "lightbox"}}<a class="lb" href="{{.Args.src}}">…</a>{{end}}
{{define "assets:lightbox"}}<link rel="stylesheet" href="/static/lightbox.css">{{end}}

The engine renders assets:lightbox once into Page.Assets when the page called ::lightbox at all — however many times — and renders nothing when it did not. A shortcode with no assets: fragment is the normal case and costs nothing to declare. Frontmatter use: [lightbox] pulls the same fragment in without a call, for a page whose script is not tied to one shortcode.

The fragment receives an empty Fragment: it emits fixed markup, not per-call markup. Two calls with different arguments still share one asset, which is what makes deduplication meaningful. Order is first-call, and nothing promises an order between two assets.

Where the files live is yours. /static/ is served verbatim and needs no engine change, which is why the reference theme's examples point there. The reference theme itself defines no assets: fragment and ships no asset (ADR-0063) — this is a mechanism, not an invitation.

Templates in the same set may call each other — {{template "picture" .}} from figure.html reaches a block defined in gallery.html, because both are parsed into the partials set. The pipeline is all that passes, and there is no way to build a value in a template, so inclusion is useful where the callee needs exactly what the caller has. Across sets it does not work: base, page, list, extras and the fragments are five separate sets, which is what stops a listing's main leaking into a bundle page (ADR-0019).

Every fragment receives the same two fields (ADR-0037):

Field	Contents
.Args	the call's key=value pairs, exactly as the author wrote them
.Pictures	images the engine gathered: one for a figure, many for a gallery, none when the call names nothing it recognises (ADR-0042)
.Lang	the language being served, so a fragment can localise words of its own through t (ADR-0067)
.Body	a container call's content, already rendered to HTML. Empty for every leaf call (ADR-0064)
.Headings	the document's headings for a ::toc call: .Level, .Text, .ID. Empty for every other call (ADR-0065)

Each picture carries:

Field	Contents
.Src	the author's own file, relative to the bundle — always usable on its own
.Srcset	the generated widths, closed by the original at its own width; empty when nothing was worth generating, or when the format has no decoder
.Width, .Height	the original's intrinsic size, for reserving the box; zero when the file could not be read

A theme emitting .Srcset must emit sizes too. The engine cannot supply it: sizes says how wide the picture will be, which is a fact about the layout and therefore the theme's (ADR-0068). Without it a browser assumes 100vw and fetches the widest variant for a thumbnail, which costs more bandwidth than serving no derivatives at all. The reference theme states its own measure — 32rem for a figure, 16rem for a gallery column above 36rem — and adds loading="lazy" to gallery entries but never to a figure, which is often the first thing on the page.

Shortcode	Template	Receives
::figure{src=… alt="…" caption=…}	figure	.Args.src, .Args.alt, .Args.caption
::gallery	gallery	.Pictures — every picture beside the bundle, in filename order
:name:	icon	.Args.name — the name as written, nothing else
:::note{title=…} … :::	note	.Args.title, .Body — the rendered content
a fenced code block	code	.Args.lang, .Args.title, and .Body — chroma's token spans, already classed (ADR-0075)
::toc{depth=N}	toc	.Headings — the document's headings in order, no deeper than depth if given
:::details{summary=… group=… open=…} … :::	details	.Args, .Body. Siblings sharing a group open one at a time, through <details name> and no script
:::aside{title=…} … :::	aside	.Args.title, .Body. Beside the text where there is room, in the flow where there is not

A fragment supplying its own words must localise them. .Lang is there for exactly that: the reference theme labels an untitled admonition with {{t .Lang "warn"}} and a contents list with {{t .Lang "contents"}}, so a Bengali page reads সতর্কতা and সূচিপত্র rather than English (ADR-0067). Words the author wrote — .Args.title, .Body — are never touched.

A code block is highlighted by the engine and framed by the theme. .Body is <pre class="chroma"> with token classes — k keyword, s string, c comment, m number, nf function, ln line number, and a line hl for a highlighted row. The palette is a stylesheet's, never inline, so dark mode is the theme's as usual. The reference theme frames it in a <figure class="code"> with the title as a <figcaption>, and stops there: a copy button needs a script, and the reference theme is gated script-free (ADR-0026), so that belongs in a theme of your own.

A container call wraps content: :::name{…}, a body, then :::. It renders through the fragment of that name with .Body already HTML, and one level only — a ::: inside closes the one it is in. A theme with no template for the kind renders nothing, and the engine writes the body out unwrapped, so an unknown kind costs an author styling and never paragraphs (ADR-0064). The reference theme defines note, warn and tip.

The icon fragment is one template for the whole set: which names exist is the theme's decision, and the engine holds no list of them (ADR-0063). Render nothing for a name you do not know — the engine then writes the author's original :name: text back, so an unrecognised icon is never dropped out of a sentence. The reference theme maps six names to Unicode characters and ships no sprite, font or asset; a theme wanting drawn icons defines a sprite in its own base.html and emits <use> from this fragment.

::include{file=…} has no fragment: an included file is content, so it renders as Markdown in place and a theme has nothing to style about it (ADR-0038).

Authored and engine-supplied data are kept apart so a src argument can never be confused with a src the engine found. Arguments are escaped by html/template like any other data, in whichever context the template puts them — which is what keeps an author's text out of the markup. A call whose template is missing renders nothing and logs; it never fails the page.

A gallery entry has no alt text: nothing in a filename supplies one, and inventing it would be worse than an empty alt on a picture the page has already introduced. A figure's alt is the author's, from .Args.alt.

Argument names are contract, added but never renamed.

Feed discovery

The engine serves Atom at /feed.xml, per section and per tag (content-model.md). A theme advertises it from the document head, which is what a reader looks for:

<link rel="alternate" type="application/atom+xml" href="{{.Site.Base}}/feed.xml" title="{{.Site.Title}}">

Only with a declared base: without one there is no feed to point at.

What is yours and what is the engine's

The engine supplies facts it alone can produce — which bundles exist, what a picture measures, where a permalink points, what a month is called in Bengali. Everything about how those facts look is yours, and the engine is audited against that line (ADR-0046, harness/architecture.md). Two consequences worth knowing:

• Where a listing offers more than one shape of the same data — .Items and .Groups — pick one. The engine is not telling you which.
• If something you want is purely visual, it is CSS or a template, and asking the engine for it is the wrong request. Widow control used to be an engine feature and is now one line of stylesheet (ADR-0045).

Typography is the theme's

The engine transforms text where no stylesheet could — smart quotes, dashes, ellipses — and stops there. How text lays out is the theme's, done in CSS: the reference stylesheet sets text-wrap: pretty on body copy and text-wrap: balance on headings, which is where widow and orphan control belongs (ADR-0045). The engine will not insert characters into an author's prose to influence line breaking.

Markup a body may now contain

.HTML is Markdown output, so the dialect decides which elements a theme has to be ready to style (content-model.md). Beyond CommonMark's own, since ADR-0058: <table> with <thead>/<tbody>, <dl>/<dt>/<dd>, <del>, <sub>, <sup>, <mark>, <abbr title=…>, and goldmark's footnote markup — <sup id="fnref:N"> in the text and a <div class="footnotes"> carrying an <ol> of notes. Headings arrive with an id. Since ADR-0078, <input type="checkbox" disabled> opening a list item — a task list, static and unclickable; the reference stylesheet unbullets those lists with :has, since goldmark adds no class to find them by.

None of it is optional and none of it is configurable: a theme that styles none of these still renders a correct page. The reference stylesheet does the minimum — a rule under each row, an indent for definitions, smaller footnotes — and nothing more (ADR-0026).

The stability rule

Fields and names are added, never renamed or removed. Absence is always legal: a template reading a field that does not exist gets the zero value and must not crash, and the engine must not make a missing field fatal at request time (ADR-0002, invariant 1). This is the View-layer freeze from architecture.md, arriving as soon as a theme exists rather than at Arc 2.

Breaking the contract is not a feature — it is a new contract version, and it needs an ADR.

What the engine provides

Provides	Detail
the page object	known fields plus an Extra bag carrying unknown frontmatter (ADR-0002)
the resolved cascade	settings after site → section → bundle resolution (ideas/deferred-decisions.md)
queries the page needs	its sequence neighbours, its taxonomy terms, its section's members
named template lookup	per-type sets; a theme redefines a named block and inherits the rest (ADR-0019)
URLs	every path the engine emits, so a theme never constructs one by hand
per-page assets	.Styles and .Scripts — the bundle's own files as finished URLs, from the frontmatter lists, with anything climbing out of the bundle already dropped (ADR-0079)
theme assets in use	.Assets — the assets:<name> fragments this page's shortcode calls and use: list asked for, rendered once each. Emit it in the head block
a head block	base.html calls {{block "head" .}}, empty by default; page.html fills it with .Assets and .Styles, because only a bundle carries assets. .Scripts is not emitted by the reference theme — it ships no <script> at all (ADR-0026, enforced), so a theme wanting the JavaScript half of ADR-0080's exception redefines this block and adds the tag. examples/demo-site/templates/page.html is a working example
chrome strings	looked up by key and language, never hardcoded English in a template — live, see above
validity windows	a template that renders time-dependent output declares one

Extras view

A request under a bundle's extras directory renders templates/extras.html, whose main block receives (ADR-0047):

Field	Contents
.Bundle	the page these files belong to, as an .Items entry — so a theme has its title and a way back
.Entries	the tree, sorted by path: .Name, .Path, .Kind, .Size, .IsDir
.Selected	absent on the bare listing; otherwise the entry the URL named
.Selected.HTML	the rendered file for a markdown or text entry, empty for anything else
.Selected.RawURL	always present — for <img src>, <object data>, or a download link

.Kind is one of markdown, text, image, pdf, audio, video, other, dir, classified by extension. An entry's .Path is relative to the extras listing, so a template can link it directly.

Selecting an entry is an ordinary link and a full page, so a sidebar-plus-pane layout needs no JavaScript. Swapping the pane client-side is a later enhancement over working markup, never a requirement.

What the engine does not provide

Layout, class names, CSS, client-side behaviour, and any choice about how something looks — including how media is embedded, how a listing is arranged, and whether something appears in a sidebar. Those are theme decisions, and a request touching them is split: a contract extension here, a change there.

The engine also does not provide a component library, a CSS build step, or a JavaScript runtime. conventions.md holds the output floor the engine itself meets — semantic HTML, zero-JS, every image carrying width, height and alt — and a theme is expected to stay inside it, but the engine does not enforce a theme's markup.

The reference theme

The binary embeds a reference theme — templates plus one small stylesheet — so a bare site root renders (ADR-0026). It exists to make this document executable: it implements every field and block named here and nothing else, and a golden-file test through it catches contract regressions before a real theme does.

It is not a design. Legibility only, no branding, no visual opinions, no JavaScript — verify.sh fails on a <script tag in it. If it starts accumulating taste, it has stopped being a reference.

It demonstrates the contract; it is not the contract. Changing it does not change what a theme may rely on — which is why verify.sh also fails when it changes without this document changing, since in practice the two drift together.

Overriding it

Each set is built from named files and only those are overlaid — base.html plus that kind's block file (page.html or list.html), and the fragments on their own (ADR-0019, ADR-0071). Overlaying every site template into every set would let a listing's main leak into bundle pages, which is the collision per-kind sets exist to prevent.

templates/theme.css in the site root replaces the reference stylesheet entirely; there is no merging.

static/ in the site root is served verbatim under /static/. Directory paths answer 404 rather than listing their contents.

Splitting a request

When a feature spans engine and theme, this repo delivers:

1. the contract extension — new fields, new named blocks, new queries, new URLs;
2. a note stating what a theme must do to use it, precise enough to act on without this conversation;
3. embedded defaults updated far enough to prove the extension works.

It does not deliver the theme. Claiming otherwise is the same error as claiming to have migrated content in a site root this repo cannot see.