bdeshi/khosra
0
0
Fork 0
Code Issues Pull Requests Releases Activity

publish a bundle's extras as a browsable tree

Browse Source 
Re-adopts the parked extras entry as ADR-0047: `extras/` inside a bundle is skipped
by the scanner entirely, so a `.md` in there is an asset with no identity and no URL
of its own. The engine enumerates the tree, sorts it by path, classifies by
extension, renders markdown and text, and offers everything else as bytes. One route
with two behaviours — `…/extras/{path}` selects an entry, `?raw` returns the file.

Almost everything it needed already existed, which is the sign the model was right:
the scanner had a directory exclusion, `Assets()` knew which bundles own a
directory, and `Lookup` already decided visibility — so a draft hides its extras
with no new check. A test proves that, including `?raw`.

Two deviations from the parked shape, both because the shape was written before the
code. The directory name is fixed rather than a cascade key, since nothing reads a
section-level setting yet. And an entry is resolved against the *enumeration* rather
than the filesystem: not being in the listing is a stronger answer than os.Root
refusing a path, and cheaper.

Selecting is a link and a full page. No JavaScript is involved, and a
sidebar-and-pane layout is the theme's business — which is the layer rule applied
before writing the feature rather than after.

Three size warnings fired as a result and were fixed by splitting at seams, not by
sharding: render.go gave up its type declarations to view.go, which is the theme
contract in Go and nothing else; serve() split into a dispatcher and serveBundle;
resolve() gave up its language-prefix step to cutLang.
This commit is contained in:
bdeshi
2026-08-01 02:23:37 +06:00
parent e79aba2b11
commit 37a3fa6ce6
16 changed files with 685 additions and 136 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/theme-contract.md
+12 -8
View File
@@ -167,18 +167,22 @@ Breaking the contract is not a feature — it is a new contract version, and it
## Extras view
For a request under a bundle's extras directory (`ideas/deferred-decisions.md`) the engine additionally provides:
A request under a bundle's extras directory renders `templates/extras.html`, whose `main` block receives
(ADR-0047):
| Field | Contents |
|---|---|
| `.Extras.Entries` | the tree: `Name`, `Path`, `URL`, `RawURL`, `Kind`, `Size`, `IsDir`, `ModTime` |
| `.Extras.Selected` | nil on the bare listing; otherwise the chosen entry |
| `.Extras.Selected.HTML` | rendered output for `markdown` and `text` kinds; empty otherwise |
| `.Extras.Selected.RawURL` | always present — for `<img src>`, `<object data>`, or a download link |
| `.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 |
`.Bundle` is the parent, so a theme has its title, language and breadcrumb. Selecting an entry is an
ordinary link and a full re-render, so a sidebar-plus-pane layout needs no JavaScript; swapping the pane
client-side is a later enhancement over working markup, never a requirement.
`.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