immich-folio/CHANGELOG.md

# Changelog

All notable changes to this project are documented here.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
Releases up to and including v0.9.2 are documented in the
[GitHub releases](https://github.com/ralksta/immich-folio/releases).

## [Unreleased]

### Added

- **First-run setup wizard at `/install`**
  ([#419](https://github.com/ralksta/immich-folio/pull/419)). A fresh deployment
  can now be configured from the browser: connect to Immich, optionally pick
  albums, name the site. Credentials are verified against the Immich server
  before anything is written, so a typo cannot produce an "installed" site that
  loads no photos. The wizard is gated by a one-time token printed to the server
  log — a deployment is reachable before it has any configuration, and without
  the gate whoever found the URL first could configure it. Credentials land in
  `content/install.json` (mode `0600`, admin password stored as an scrypt hash);
  environment variables continue to take precedence, so rotation still works by
  setting a variable. Configuring everything by hand remains fully supported.
- **Custom favicon upload** in admin Settings › General
  ([#422](https://github.com/ralksta/immich-folio/pull/422)). SVG, PNG, ICO or
  JPEG, stored in the writable `content/` volume and served through
  `/api/favicon` with a policy that stops an uploaded SVG executing script. A
  Reset button restores the bundled default.

### Changed

- **A gallery with no albums is now a valid, rendered state**
  ([#421](https://github.com/ralksta/immich-folio/pull/421)) instead of an error
  — the setup wizard can finish without picking one, and albums can be added
  later in `/admin`.
- **The Immich URL may end in `/api`** without breaking every request
  ([#421](https://github.com/ralksta/immich-folio/pull/421)). The suffix was
  appended unconditionally, producing `.../api/api`.

### Documentation

- **README documents the setup wizard**, what it writes, and that
  `content/install.json` holds credentials — so a backup of `content/` is
  understood to include your Immich API key. The Docker examples no longer mount
  `content/` read-only: the wizard, the admin panel and the backup rotation all
  write into it, and `:ro` silently breaks all three.
- **Contributors are credited in the README.**

### Security

- **Next.js 16.3.0** — picks up the fix for CVE-2025-13465 in Next's vendored
  lodash ([#402](https://github.com/ralksta/immich-folio/pull/402)).

### Internal

Nothing user-facing; recorded so the next release notes are complete.

- **CI annotates unformatted files in a PR without blocking it**
  ([#424](https://github.com/ralksta/immich-folio/pull/424)). Prettier is
  configured as an eslint error but had never run in CI, so part of the tree
  predates it. Failing on that would make a PR red for merely touching an old
  file; reformatting the tree in one commit would bury every future diff in
  churn. The check runs over the files a PR changes and warns.

- **Dependency PRs now target `dev`**, and CI runs on pull requests to `dev` as
  well ([#411](https://github.com/ralksta/immich-folio/pull/411)). The workflow
  previously triggered on `main` only, so a PR against `dev` carried no checks
  at all. `CONTRIBUTING.md` and the PR template now state the target branch
  ([#412](https://github.com/ralksta/immich-folio/pull/412)) — it was nowhere
  documented before.
- **`scripts/screenshots.ts` type-checks against sharp 0.34 and 0.35**
  ([#410](https://github.com/ralksta/immich-folio/pull/410)). sharp arrives
  transitively through Next, and 0.35 moved from `export =` to ESM: the module
  namespace stopped being callable and the factory moved to `.default`. The
  Next bump above would otherwise have broken `npx tsc --noEmit`.
- Dev-dependency bumps: prettier 3.9.6, eslint 9.39.5, `@types/leaflet` 1.9.22,
  and `github/codeql-action` v4.

## [0.10.0] — 2026-08-10

### Added

- **Photo Essay mode** — storytelling pages with an RSC markdown parser and
  fullbleed/pair layouts, plus a visual essay block builder in the admin panel.
- **Client proofing** — favorite selection with compact URL bitmasking and an
  export modal.
- **Subpage enable toggle** — deactivate a subpage without deleting it.
- **SEO** — configurable subpage title template, metadata descriptions, and
  `generateMetadata` on the about page.
- **New theme preset `studio-modern`.** The Leica language of `studio` rebuilt
  around the precision grotesque Archivo, with IBM Plex Mono for every piece of
  photographic metadata. Hairline rules, zero radius, an indexed hero navigation
  with album counts, an always-visible caption bar under album covers, and a
  film-edge EXIF strip in the lightbox. Selectable in the admin panel, the dev
  toolbar, and `content/settings.yaml`. See [docs/theming.md](docs/theming.md).

### Security

- `GET /api/admin/analytics` now requires an admin session.
- Docker images are scanned with Trivy on every publish; results land in the
  GitHub Security tab.

### Changed

- **Album sort order now mirrors the Immich timeline** ([#350](https://github.com/ralksta/immich-folio/issues/350)). Albums were
  sorted by `fileCreatedAt`, the capture instant in UTC. Immich sorts its
  timeline primarily by `localDateTime` — the capture time in the
  photographer's local zone — and uses `fileCreatedAt` only as a tie-breaker.
  The two keys are identical for the vast majority of albums; they diverge for
  albums spanning time zones, where the order shown in Immich Folio no longer
  matched the Immich UI. The sort keys were changed accordingly, and
  unparseable dates now fall back to `0` instead of `NaN` (a `NaN` comparator
  makes `sort()` free to return any permutation).

### Fixed

- **Cache staleness** — `?fresh=1` bypass, an admin diagnostic banner for albums
  Immich returns empty, and revalidation after admin saves.
- **Admin status panel reported two faults that were not faults** ([#341](https://github.com/ralksta/immich-folio/issues/341)).
  `settings.yaml` was treated as mandatory although `getConfig()` falls back to
  defaults without it, so anyone running with only a `gallery.yaml` saw a
  permanent "Config Integrity: Degraded". Only a file that exists and cannot be
  parsed counts as degraded now. A failed status request was also rendered as if
  it were a result — an expired admin session looked identical to a real
  outage — so there is now a third state for "the check did not run".
- **Lightbox showed its photo counter twice.** The counter renders a
  screen-reader label ("Photo 3 of 53") alongside the compact display
  ("3 / 53"), but `.sr-only` was not defined in any stylesheet, so both strings
  were visible on top of each other.
- **Docker** — health check targets `127.0.0.1` instead of `localhost`, base
  image moved to `node:22-alpine`.
- **The Trivy scan never ran.** The publish workflow referenced
  `aquasecurity/trivy-action@0.29.0`, but that repository's tags carry a
  leading `v`, so the job failed during action setup — before the image was
  built. No image was published for the first v0.10.0 attempt, and no scan had
  run since the step was introduced. The action is now pinned to a commit SHA
  ([#409](https://github.com/ralksta/immich-folio/pull/409)).
- **Docs** — the "nature / travel journal" example in `docs/theming.md` used a
  preset named `botanica` that does not exist; copying it produced an
  `Unknown theme preset` error. It now uses `editorial`.
- **Map page ignored the theme.** `app/map/map.css` referenced custom properties
  that never existed (`--font-heading`, `--font-body`, `--border-color`,
  `--radius`), so the map title, popups, and container fell back to browser
  defaults instead of the configured fonts, borders, and radius. This affects
  every preset — the map now picks up the theme like the rest of the site.

### Upgrade notes

**No migration is required.** No configuration schema changed, and the six
existing presets render exactly as before. Pull the new image, restart, done.

**Rolling back after switching presets needs one edit.** If you select
"Studio Modern" and later downgrade to a version that predates it, the
`theme.preset: studio-modern` left in `content/settings.yaml` is a preset the
older version does not know, and config loading fails with:

```
Unknown theme preset "studio-modern". Valid presets: studio, minimal, editorial, classic, noir, monograph
```

Set `theme.preset` back to one of the listed presets in `content/settings.yaml`
before downgrading. `/admin` stays reachable if you hit this, so the change can
also be made after the fact.

**If you copied `docker-compose.override.yml.example`, update your health
check by hand.** The example now uses `wget -O /dev/null` instead of
`--spider`, but your own `docker-compose.override.yml` is not tracked by git,
so pulling the new version does not touch it — and a health check defined
there overrides the one baked into the image. `--spider` does not read the
response body and disconnects mid-RSC-stream; when that abort coincides with a
slow render after `CACHE_TTL` expiry, Node tears down the `TransformStream`
controller while Next.js is still writing into it:

```
TypeError: controller[kState].transformAlgorithm is not a function
```

Replace `"--spider"` with `"-O", "/dev/null"` in your override file:

```yaml
healthcheck:
  test: ['CMD', 'wget', '--no-verbose', '--tries=1', '-O', '/dev/null', 'http://127.0.0.1:7211/']
```

A full GET checks the same thing without the race. Installations without an
own health check need no action — the image ships the fixed one.