bdeshi
53d679728d
The human asked whether widow prevention belonged in the backend at all. It did not, and it broke two rules already written down: the theme contract says the engine decides nothing about how something looks, and ADR-0034 says authored body text is the author's — while this inserted U+00A0 into that text. The practical harm follows from the layer error rather than from a coding mistake. The engine cannot see the line box, so joining the last two words is a guess that can overflow a narrow viewport, and a reader copying the paragraph gets a non-breaking space in their clipboard. `text-wrap: pretty` and `text-wrap: balance` in the reference stylesheet know the line box and need no bytes in the content. 108 lines of engine deleted for one CSS declaration. The typographer stays: turning `--` into an en dash is a text transformation no stylesheet can express, which is exactly the distinction the new layer test draws. Also worth recording: this took the Extensions counter from 3 back to 2. A threshold reached by a feature that should not have existed was never a threshold.
107 lines
6.0 KiB
Markdown
107 lines
6.0 KiB
Markdown
# Extensions
|
||
|
||
The plugin story, and the gate keeping it from arriving early.
|
||
|
||
**STATUS: one feature exists.** `internal/ext/shortcodes` is the first, listed in `cmd/khosra/wire.go`
|
||
(ADR-0027) — one directory, called explicitly, correct and sufficient until the counters say otherwise. The
|
||
`Extension` struct below is still unbuilt; this document exists so the eventual shape is known, not so it
|
||
can be built now.
|
||
|
||
How a feature reaches the engine today: `cmd` builds the list, so nothing under `internal/` knows which
|
||
features exist. A feature that must emit markup is handed `render.Partial` and renders through a theme
|
||
template, because deciding markup is not a feature's job (ADR-0036).
|
||
|
||
A feature that needs to know *which bundle* is rendering reads `render.OriginFrom` off the parse context —
|
||
the bundle's directory plus the rooted `fs.FS`, so a path in a call resolves against the bundle and cannot
|
||
leave the site root (ADR-0031). It is available while parsing, not while rendering, so anything a feature
|
||
must read from disk it reads then.
|
||
|
||
## The gate
|
||
|
||
| Stage of growth | What a feature looks like | Trigger to advance |
|
||
|---|---|---|
|
||
| Now (0–2 features) | Its own directory under `internal/ext/<name>/`, called explicitly from `wire.go` | — |
|
||
| Transform counter due | Extract the Stage pipeline: an ordered `[]Stage` in one wire file | `state.md` |
|
||
| Extension counter due | Extract the `Extension` struct below; move each into `internal/ext/<name>` | `state.md` |
|
||
| After Arc 2 | Composition only; the core no longer grows | Arc 2 closes |
|
||
|
||
`state.md` holds the thresholds and is the only place they are written. Do not extract early. Do not
|
||
"prepare".
|
||
|
||
## Target shape
|
||
|
||
Compile-time registry. No `plugin.so`, no `init()` side effects, no discovery, no config file listing
|
||
plugins. One slice, one file, source order — the order *is* the semantics.
|
||
|
||
Compile-time is not a preference: Go's `plugin` package forbids a static binary and demands an exact
|
||
toolchain match, which the container target (ADR-0010) rules out. Dynamic loading buys only
|
||
extension-without-recompiling, worth nothing to the single author (ADR-0006) holding commit access.
|
||
The registry costs a few hundred lines that render zero pages — hence real callers before a contract.
|
||
|
||
```go
|
||
// internal/ext/ext.go — the whole contract, once earned.
|
||
type Extension struct {
|
||
Name string
|
||
Stages []Stage // ordered; Phase decides placement
|
||
Views map[string]View // named, referenced by frontmatter `view:`
|
||
Shortcodes map[string]Shortcode // trusted content only (ADR-0003)
|
||
Effects []Effect // derived artifacts and outbound calls, off the request path
|
||
Adapters []Adapter // Interaction sources, Arc 3
|
||
Routes []Route // additional URL cases, via the resolver
|
||
}
|
||
```
|
||
|
||
`cmd/khosra/wire.go` holds the only list of enabled extensions — it exists now, holding one line. Enabling
|
||
or disabling one is a one-line diff and a rebuild. Removing one leaves no trace elsewhere — that property is
|
||
the test of whether the contract is right, and it is testable today: empty the list and the engine still
|
||
builds and serves, minus that feature.
|
||
|
||
## Stage phases
|
||
|
||
An ordered list, not a dependency graph. Two stages needing a graph to be correct are one stage
|
||
wearing a disguise.
|
||
|
||
| Phase | Operates on | Examples |
|
||
|---|---|---|
|
||
| `PhaseLoad` | raw bytes + frontmatter | translation fallback. *Not* includes: they turned out to be parse-phase, because splicing another file's parsed nodes into a page is invalid rather than merely awkward (ADR-0038) |
|
||
| `PhaseParse` | the parsed Markdown tree | shortcodes, transclusion, image derivatives |
|
||
| `PhaseMarkup` | rendered HTML fragments, code spans skipped | nothing, and possibly nothing ever. Everything expected here belonged somewhere else: smart quotes and dashes are a Markdown parser option, chrome localisation is a template function (ADR-0034), and widows turned out to be CSS (ADR-0045). A phase with no inhabitants is worth noticing before it is built |
|
||
| `PhasePage` | the assembled page object | OpenGraph, JSON-LD, related posts, series nav |
|
||
| `PhaseOutput` | the final byte stream | minification, dithering, gemtext conversion |
|
||
|
||
Every Stage runs on every bundle unless a cascade key disables it (`ideas/deferred-decisions.md`), and declares its trust
|
||
requirement. A Stage evaluating templates or shortcodes runs in trusted mode only, and the pipeline
|
||
refuses it otherwise — enforced in code, not by convention, and
|
||
tested with an untrusted-input case.
|
||
|
||
## Rules for any extension
|
||
|
||
1. Deletable without trauma. Removing the package leaves the engine building and serving.
|
||
2. Reads only what already exists on the page; adds through the `Extra` bag, never by widening the
|
||
core struct for its own convenience.
|
||
3. Owns its output files under a namespaced path, or none.
|
||
4. No new dependency without an ADR — extensions get no looser budget than the core, and their Go
|
||
lines count against `EXT_LOC_MAX`. Presentation features (OpenGraph, galleries, series nav,
|
||
related posts) belong in templates and frontmatter where they cost nothing; reach for Go only when
|
||
there is real logic.
|
||
5. Failure degrades: a broken extension logs and is skipped, never takes a request down.
|
||
6. Needing a permanent external service or a primitive change makes it a **trunk** — see
|
||
`exploration.md`.
|
||
7. One directory, no sibling imports, and a `doc.go` in this shape (ADR-0027):
|
||
|
||
```go
|
||
// Package feeds emits RSS and Atom for the primary feed and each section.
|
||
//
|
||
// Contributes: Effect (on change).
|
||
// Cascade keys: feeds.enabled, feeds.limit.
|
||
// Contract fields: none.
|
||
// Not doing: JSON Feed, WebSub — separate features if wanted.
|
||
package feeds
|
||
```
|
||
|
||
## ContentAPI
|
||
|
||
A thin internal write path, introduced **with comments** in Arc 3 and not before. It exists so a
|
||
second client (admin panel, Micropub endpoint) becomes possible without the engine growing a UI.
|
||
Read paths keep going straight to the filesystem; git remains the source of truth.
|