Themepack spec draft (draft 2)

This is a rough draft of a specification for "theme packs" geared towards Lagrange, but they can be reused by other apps as well.

example.themepack

A Themepack file:

• is written in TOML
• has the traditional file extension .themepack
• uses the MIME type application/gmi.themepack+toml ("application" used since it configures an application)
• can be automatically applied when clicked, under some circumstances

A Themepack ZIP pack:

• contains only .themepack files and a recommended themepacks.toml index/behavior file
• has the traditional file extension .themepacks.zip
• uses the MIME type application/gmi.themepack+zip
• does not automatically apply; enhanced linking behavior can be used instead

Once a themepack is downloaded, the downloaded copy alone should be used. Don't look it up again unless the user prompts it. (Your client may remember where a themepack was downloaded from, so that you can "check for updates" from within your client.)

Automatic application conditions

A themepack can be automatically applied if all of the following conditions are true upon clicking a link:

• The link goes to a .themepack file (this should be loaded in the background, as a picture would be)
• The response from following the link has a "success" status code (20, or equivalent)
• No redirects were followed
• No inputs were collected
• The returned file has an appropriate MIME type (application/gmi.themepack+TOML)
• The returned file is valid (i.e. has no syntax errors, includes a domain)
• The theme domain includes the page currently being viewed
• The theme domain includes the themepack file itself

If a themepack cannot be automatically applied, confirmation should be gathered before applying the theme pack. The user should be warned of the domain, site name, and the presence of each feature (menubar, colors, fonts, etc). If there are any external resources referenced, each one should be warned for, and persisted alongside the themepack (so it does not get re-fetched except during manually-triggered updates). The confirmation page should also include (a way to view) the actual TOML file itself.

After automatically applying a themepack, the page it was linked to on should be restyled immediately, but not reloaded.

When following a link to a themepack which is already loaded and up to date, if possible, a client should navigate to the confirmation page anyway.

Themepack TOML Format

• domain (REQUIRED, at root) — The "prefix" that the theme applies to.

If this is omitted, it CANNOT be automatically applied. This may be useful to add global themes in the future but this spec is not built to handle that case.

The domain prefix MUST include the hostname that it applies to. If no scheme (i.e. spartan://) is provided, Gemini should be assumed as the default. If no port is provided, it should be assumed to be the default port of the scheme used (so, 1965 by default). Finally, if no path is provided, the theme applies to the entire site, EXCEPT areas with more specifically applied themes or "user" areas (Lagrange considers at least /users/ and /~... prefixes).

[theme]

• site_name (optional) — The displayed name of the site.
• tagline (optional) — A slogan, tagline, caption, or summary to display below the site name, or to describe the site with.
• favicon (optional, 1 character) — The default icon to display for the site.

A bookmark icon will override this. Additionally, unlike bookmark icons, this applies to the "domain" of the site only, instead of the entire site.

• fonts (optional, an array) — URLs to fonts to apply (ttf, otf, woff, woff2, etc.).

[lagrange.theme]

This option is chiefly intended for Lagrange and Lagrange-like clients like Profectus.

• seed (optional) — A theme seed. A string that's used as an RNG seed to generate the color scheme.
• colors (optional, a 3 element array of string color codes) — The three base colors to build the theme from.

Primary, accent/secondary, and tertiary for good measure.

This does not guarantee your exact chosen color will appear, but the greatest chance for that lies with the primary color.

• fonts (optional, an array) — URLs to font packs to apply.

[menubar]

This section defines a menubar. I don't know if this will ever be used, but a man can dream.

Keys (names) are the displayed link names, and the values are the link destinations. Offsite or off-"domain" links may show icons, even if the links don't by default.

Extra whitespace within link names should be minimized to make menubar links more distinct from each other. When a site menubar is displayed, the focus is put after the menubar by default. There should be a shortcut for accessing the site menubar.

Instead of a menubar, this can be implemented as an in-site sidebar or a client sidebar, as you wish.

Themepacks ZIP Structure

TODO