scavold 0.2.0-rc.1 → 0.2.0-rc.11

package/CHANGELOG.md

@@ -0,0 +1,348 @@
+# Changelog
+
+All notable changes to Scavold are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), versions follow
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+While the version stays below `1.0.0` and carries a pre-release suffix, breaking
+changes may occur in any release.
+
+## [Unreleased]
+
+## [0.2.0-rc.11] — 2026-10-01
+
+### Added
+
+- A container opening a page carries an empty `data-leading` attribute, and the page
+  data name it as `leadingContainer` — known before the content renders, so a layout
+  can arrange its own parts around a cover at the top of a page, e.g. move its
+  breadcrumb below it. Both are information only; nothing changes for a theme that
+  does not ask.
+
+## [0.2.0-rc.10] — 2026-10-01
+
+### Added
+
+- `:::cover` shows an image or a video across the full width and height of the
+  window, cropped to fit, with the block's content laid on top. An image comes with
+  all its variants and a `sizes` value that accounts for the cropping; a video plays
+  muted in a loop while at least half of it is on screen, stays still for visitors
+  asking for reduced motion, and always has a button to pause it. The editor offers it
+  as a section type.
+- A container argument declared as `media-file` that names an image hands its
+  component the variants and dimensions as well, as `data-<arg>-srcset`,
+  `data-<arg>-webp-srcset`, `data-<arg>-width` and `data-<arg>-height`.
+- `<ScavoldImage>` takes `loading` and `fetchpriority`, for an image at the top of a
+  page.
+- `useAutoplay()` brings the same autoplay behaviour to a site's own video component.
+
+### Changed
+
+- A `:::video` with `autoplay` plays only while at least half of it is on screen, and
+  pauses when scrolled away — unless the visitor turned the sound up. It stays paused
+  for visitors whose system asks for reduced motion, and once the visitor paused it.
+  The `autoplay` attribute is no longer part of the markup: it started the video at
+  once, wherever it was on the page and before reduced motion could be checked.
+
+### Removed
+
+- The `overlay` and `controls` arguments of `:::video`. Use `:::cover` for a video
+  with content on top: the background mode had no way to pause a looping video, which
+  WCAG 2.2.2 requires, and ignored reduced motion. A `:::video` now always is a player
+  with its controls; a block still carrying `overlay` renders as one, with its content
+  as fallback text. `useVideo()` no longer returns `overlay` and `controls`, and the
+  `.scavold-video--overlay`, `.scavold-video__media` and `.scavold-video__overlay`
+  classes are gone.
+
+## [0.2.0-rc.9] — 2026-10-01
+
+### Fixed
+
+- An image wider than the largest of `image_widths` named that width twice in its
+  `srcset`, and had its widest variant written twice at the same time.
+
+## [0.2.0-rc.8] — 2026-10-01
+
+### Added
+
+- `SECURITY.md` says how to report a vulnerability and which versions receive fixes,
+  beside the [cratly security policy](https://cratly.io/security) it belongs to.
+  Every release's tag pipeline keeps a CycloneDX SBOM of what a site installs along
+  with scavold, and checks those packages for known vulnerabilities; `bun run sbom`
+  and `bun run audit:runtime` do the same locally.
+
+### Fixed
+
+- A photo whose camera stored it turned, saying in its EXIF data how to show it, came
+  out upside down or lying on its side on the site, and a portrait got the variant
+  widths of a landscape. The variants are now turned the way the photo says, and
+  measured by the width it is shown at. Every image gets new variant names once, so
+  variants kept between builds are written again rather than served as they were.
+
+### Security
+
+- `sharp` 0.35, whose bundled libvips and libheif fix vulnerabilities reported against
+  0.34 (GHSA-f88m-g3jw-g9cj, GHSA-rgj7-g3m4-5g8c). It needs Node 20.9 or newer, and so
+  does scavold now.
+
+## [0.2.0-rc.7] — 2026-09-29
+
+### Fixed
+
+- A link to a media file whose extension VitePress does not know, such as `.diff`,
+  pointed at the file name with `.html` appended and therefore at nothing. It now names
+  the file as published.
+
+## [0.2.0-rc.6] — 2026-09-13
+
+### Added
+
+- `aliases` in a page's front matter names the former addresses it replaces, and
+  `retired_urls` in `.cratly.config.yaml` those that are not coming back. A site taking
+  over from an existing website declares them once and the build writes
+  `cratly-redirects.json` into its output: an address, where it went, and `301` or `410`.
+  The format names no server — only a server-side redirect passes a ranking on, and which
+  server that is cratly does not assume, so the deploy step translates the file for its
+  target. Keeping an address is still better than redirecting to it, which is what `url`
+  is for; the build refuses an alias that two pages claim, or that the site serves itself
+  and the redirect would therefore hide.
+- Every build now ends by reading its own result. A page that the generator listed but
+  never wrote, or a script a built page names and the output does not contain, ends the
+  build with the file named — the two states a bundling fault leaves behind while the log
+  says "build complete". Links and images pointing at absent files are reported and left
+  to the site, since one may legitimately name a path the web server provides. Turn it
+  down with `verify: { content: false }` or off with `verify: false`. A reference is read
+  the way a browser reads it: a relative one against the address of the page holding it, so
+  a link that forgot its protocol — `[Website](./www.example.com)`, which the build turns
+  into a sibling page nobody wrote — is seen as well. Proven against the
+  case-collision that used to build green: the page missing from the output is the only
+  trace it leaves on a file system that ignores letter case, and that is now enough.
+  Everything found also goes to `.cratly/build-report.json`, written before the build is
+  ended rather than after, each entry naming the source file an author would open. A build
+  log is read by whoever has access to it; a file can be handed to whoever wrote the page.
+- `ignoreDeadLinks` now defaults to `true`. VitePress ends a build on a dead link and does
+  so before writing anything, which leaves the reason in a job log that whoever wrote the
+  link often cannot read, and lets one typo stand between a finished page and its
+  publication. Scavold finds the same mistake in the finished output and reports it there
+  instead. Whether it should also stop a pipeline is a question whose answer differs per
+  branch, so it is left to CI: the site template fails a merge request over it and lets the
+  default branch deploy, since blocking there would answer a broken link with a stale site.
+  Ask for VitePress' abort back with `ignoreDeadLinks: false`.
+- A site whose page paths collide in VitePress's eyes now learns that from Scavold, by
+  name, before the build starts. VitePress identifies a page by its path flattened into
+  a single name — slash becomes underscore, and the page-hash map lower-cases it — and
+  uses that name for the page's bundle entry, its server module and its client chunk.
+  Two pages meeting there overwrite each other: either the build dies at render time in
+  `pageChunk.imports`, naming no file, or it succeeds and ships two pages pointing at a
+  script that was never written. Scavold now reproduces that identity when it reads the
+  config and aborts with both file names, whether they collide through an underscore in
+  a file name (`de_kontakt.md` beside `de/kontakt.md`), through letter case alone, or
+  through a `url` alias landing on a path another page already owns as its file — the
+  case the previous alias check, which compared aliases only with each other, let pass.
+- `date` and `datetime` join the type vocabulary of `frontmatter_fields` and of a
+  container's `props`. Scavold passes such a value through as the ISO 8601 text it is;
+  what changes is that the cratly editor now offers a date picker for it instead of a
+  plain text box. A `datetime` always carries an offset — a time of day without one is
+  a different moment on every machine that builds the site.
+
+### Changed
+
+- `@cepharum/vue3-i18n` moves to `2.0.0`, two majors on from the `0.5.4` a site would
+  have installed. Scavold uses `useL10n`, `setLocale` and `setLoader`, none of which
+  changed; what 2.0 breaks are the locale helpers now returning full BCP-47 tags, and
+  Scavold calls none of them. A site inherits the new version with its next install, and
+  gains what 2.0 adds along the way: regional locales overlaying a bare language, plural
+  and gender selection resolved through `Intl`, and `Intl`-backed formatters in
+  placeholders.
+
+### Fixed
+
+- `lib/href.js` ships the declarations it had been missing since it was split out, so
+  `typecheck` passes again — and the pipeline runs it now, which is why it could go
+  unnoticed at all. Nothing about the module changed; TypeScript simply had nothing to
+  read about it, and treated every href the hierarchy composes as `any`.
+
+## [0.2.0-rc.5] — 2026-08-17
+
+### Added
+
+- `:::pagelist` dates its entries the way the site wants them: `time-style` adds the
+  time of day, `timezone` names the zone the timestamps are read in, and both accept
+  `iso` alongside the `Intl` styles, writing `2020-10-20 12:16` in every language. The
+  default is unchanged — the date alone, read in UTC, which is where a front matter
+  value carrying no time of day belongs.
+- `formatTimestamp()` in `scavold/lib/dateFormat.js` renders timestamps the same way
+  for a theme's own components — a byline under a post's title, say. It is free of Vue
+  and VitePress and depends on its arguments alone, so pre-rendered markup and the
+  browser agree.
+
+### Changed
+
+- A `:::pagelist` that paginates reaches every page it found: `limit` now defaults to
+  `0` when `per-page` is set, rather than capping the selection at five entries and
+  leaving a pager to turn the pages of those five. A limit the author sets still wins.
+- Every link a site generates — menus, breadcrumbs, page lists, the feed, redirect targets
+  — names the file the page is built into: `/blog/post.html`, `/blog/index.html`,
+  `/index.html`. Links used to leave the extension off while VitePress's own markdown
+  links carried it, so one site spoke two dialects and the shorter one only worked on
+  servers that go looking for the file. Naming it is answered on the first attempt, and
+  the sitemap now lists the same URLs. The address bar still shows `/` and `/blog/`:
+  VitePress's router shortens them while navigating.
+
+### Fixed
+
+- The site's own `index.md` is no longer linked as `/index`, a URL no server has to
+  answer. The rule for a page's URL existed in three copies and now lives in
+  `lib/href.js` alone.
+- Scavold's built-in translations come from the bundle. They used to be fetched from a
+  URL that no build emits, so every page requested a file that was not there and the
+  interface silently fell back to English, whatever language the site is in.
+
+## [0.2.0-rc.4] — 2026-08-15
+
+### Added
+
+- `metaChunk` is on by default, keeping VitePress's page-hash map out of the inline
+  scripts. Its content changes with every build, so under a content security policy that
+  names script hashes it has to be updated on the server for every deploy — and when it
+  is not, the map is blocked and the client side of the site stops working while the
+  pre-rendered HTML still shows. What stays inline are VitePress's own two snippets,
+  whose hashes hold still. `metaChunk: false` in the site's own config wins.
+- An RSS feed, written at the end of the build when `augmentConfig` is given a `feed`
+  option: the pages of a section, newest first, with their excerpt as the entry text.
+  Announced are pages carrying a `date` — a feed is a chronology, and an entry a reader
+  cannot place in it is noise. Absolute links need a hostname, taken from
+  `sitemap.hostname` unless the feed names its own; without one the build says so and
+  writes nothing. Several feeds may be declared, one per language say. The feed is
+  compiled from the page hierarchy and is unrelated to `:::pagelist` — a page may appear
+  in three lists and in the feed, in the feed alone, or in neither.
+- Front matter `hide` names surfaces: `"menu"`, `"breadcrumb"`, `"list"`, `"feed"`, a
+  list of several, or `true` for all of them. A page can now be kept out of the
+  navigation and the feed while staying in the lists.
+- `:::pagelist` pages its entries in the browser with `per-page`: only the current page's
+  entries are rendered, the page shown is remembered as `?page=2` so returning from an
+  entry lands where the reader left off, and the pager is a labelled `<nav>` with a
+  status line and buttons.
+- New built-in section `:::pagelist`, rendered by `<ScavoldPageList>`: links a
+  configurable number of the site's own pages — the latest posts of a blog, a section's
+  sub-pages, a list of downloads. Which pages are listed is addressed as in
+  `<ScavoldMenu>` (`from`, `from-root`, `from-path`, plus `deep` for pages filed in
+  sub-folders), and `limit`, `offset`, `sort` and `reverse` decide which of them appear
+  in what order. Entries are a plain list of links by default; the `teaser`, `images`,
+  `dates` and `heading-level` arguments turn them into teaser cards. Anything written
+  inside the block is rendered above the list. Each entry is a single link around all
+  of its parts, so a screen reader announces it once rather than three times.
+- Pages carry teaser data on their hierarchy node, so a list shows content maintained
+  in the target page rather than repeated in the list: `date` (normalised to an ISO
+  timestamp and rendered in UTC, so a date-only value never shifts a day), `excerpt` —
+  from `excerpt` or `description` front matter, otherwise derived from the page's
+  opening prose and trimmed at a word boundary — and `image`, from `image` front matter
+  or the first image in the page body. Front matter images now go through the
+  responsive image pipeline too, which no pass reached before, as no Markdown syntax
+  reveals them.
+- `.cratly.config.yaml` accepts `excerpt_length` (default `200`) to control how long
+  derived excerpts get; `0` switches the derivation off for sites that would rather not
+  carry it in every page's payload.
+- Front matter `hide` accepts `"list"`, hiding a page from page lists only — a draft
+  post stays reachable by URL without being teased anywhere.
+- `useHierarchy()` exposes `collectPages()`, `nodeHref()`, `nodeLabel()` and
+  `nodeTitle()`, the last two separating the short navigation text menus want from the
+  full title a teaser heading wants. `<ScavoldMenuItems>` uses them instead of its own
+  copies.
+
+## [0.2.0-rc.3] — 2026-08-09
+
+### Added
+
+- Media that is not an image is published. Files an author uploads into the media folder
+  — PDFs, videos, archives — are copied into the static output keeping their path, and
+  references to them are rewritten to the URL the built site serves: Markdown links,
+  and container arguments declared as `media-file` such as a video's `src` or `poster`.
+  Previously only Markdown image syntax was handled, so a linked document or a video
+  resolved to a dead URL although the editor offered exactly that reference. Where a
+  single URL is needed instead of a srcset — a `poster`, a link to an image — the
+  largest generated variant is used.
+
+### Fixed
+
+- Flag arguments on a container reach components that declare them as props. Bare words
+  used to become the container's `class` only, while `useVideo()` reads its booleans
+  from `data-*` props — so the documented `::: video src=… overlay autoplay loop`
+  rendered a plain inline player with no background mode, no autoplay and no loop, and
+  failed silently. Flags are now emitted as an empty `data-<flag>` attribute in addition
+  to the class. A flag a component does not declare as a prop shows up in the markup as
+  an empty attribute (`<section class="highlight" data-highlight>`).
+
+### Added
+
+- Container blocks work with any name, declared or not: an undeclared name is rendered
+  by `ScavoldContainer` instead of leaving its fences in the page as literal text. To
+  keep a typo from silently becoming a `<div>`, the build reports each undeclared name
+  once; declaring it in `.cratly.config.yaml` silences the report and adds typed
+  properties for the editor.
+
+### Fixed
+
+- `registerContainers()` and the component reference described `ScavoldContainer` as a
+  catch-all fallback, which it was not — no rule was registered for unknown names.
+
+## [0.2.0-rc.2] — 2026-08-06
+
+### Fixed
+
+- `media_folder` from `.cratly.config.yaml` is honoured again. `augmentConfig()` read
+  every other folder declaration but this one, so image resolution fell back to the
+  pages folder: any image stored in the editor-managed media folder was reported as
+  missing and failed the build. No site could use an image from `media/`.
+
+### Changed
+
+- The folder precedence rules moved into an exported, pure `resolveFolders()`, so an
+  explicit `srcDir` / `mediaDir` in the VitePress config beating the YAML declaration
+  is covered by unit tests instead of only by a running site.
+
+## [0.2.0-rc.1] — 2026-08-05
+
+First published release. Version `0.1.0` existed in-tree only.
+
+### Added
+
+- **Section-type manifest.** The build emits `.cratly/sections.json`, describing the
+  typed properties each container accepts, so the cratly editor can render matching
+  controls. Container declarations in `.cratly.config.yaml` support `props` (with
+  `flags` and `kv` as shorthands) and are merged with Scavold's built-in sections.
+- **Background videos.** The `video` container accepts `overlay` to place the video
+  behind the block's content, plus `controls` to bring the native controls back in
+  that mode.
+- Type declarations for both entry points (`scavold`, `scavold/config`), a `typecheck`
+  script, and the MIT licence text the package always claimed to carry.
+
+### Fixed
+
+- `Scavold.UserConfig` in the shipped declarations was a self-referential type alias
+  (TS2456) and now aliases VitePress's `UserConfig`.
+
+### Known issues
+
+- Flag arguments on the `video` container have no effect: bare words become the
+  container's `class`, while `useVideo()` reads its booleans from `data-*` props, which
+  only `key=value` arguments produce. Use `overlay=1 autoplay=1 loop=1` until this is
+  resolved.
+- Container names that are neither built in nor declared in `.cratly.config.yaml` are
+  not parsed as containers at all, despite `ScavoldContainer` being documented as a
+  catch-all fallback.
+- Only images are processed out of `media_folder`; other file types (video, documents)
+  are never copied into the build output and have to live in the static folder.
+
+[Unreleased]: https://gitlab.com/cratly/scavold/-/compare/v0.2.0-rc.11...main
+[0.2.0-rc.11]: https://gitlab.com/cratly/scavold/-/compare/v0.2.0-rc.10...v0.2.0-rc.11
+[0.2.0-rc.10]: https://gitlab.com/cratly/scavold/-/compare/v0.2.0-rc.9...v0.2.0-rc.10
+[0.2.0-rc.9]: https://gitlab.com/cratly/scavold/-/compare/v0.2.0-rc.8...v0.2.0-rc.9
+[0.2.0-rc.8]: https://gitlab.com/cratly/scavold/-/compare/v0.2.0-rc.7...v0.2.0-rc.8
+[0.2.0-rc.7]: https://gitlab.com/cratly/scavold/-/compare/v0.2.0-rc.6...v0.2.0-rc.7
+[0.2.0-rc.6]: https://gitlab.com/cratly/scavold/-/compare/v0.2.0-rc.5...v0.2.0-rc.6
+[0.2.0-rc.5]: https://gitlab.com/cratly/scavold/-/compare/v0.2.0-rc.4...v0.2.0-rc.5
+[0.2.0-rc.4]: https://gitlab.com/cratly/scavold/-/compare/v0.2.0-rc.3...v0.2.0-rc.4
+[0.2.0-rc.3]: https://gitlab.com/cratly/scavold/-/compare/v0.2.0-rc.2...v0.2.0-rc.3
+[0.2.0-rc.2]: https://gitlab.com/cratly/scavold/-/compare/v0.2.0-rc.1...v0.2.0-rc.2
+[0.2.0-rc.1]: https://gitlab.com/cratly/scavold/-/tags/v0.2.0-rc.1