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

package/docs/NEW-SITE.md

@@ -34,6 +34,41 @@ Add one test that pins the contract version the site was built against and one
 that asserts `missingMigrations(appliedFilenames)` is empty. See
 `tests/platform-contract.test.ts` in any existing site for the exact shape.
 
+The current contract is **v2**, because saving a page version — an ordinary
+draft save included — is a single database function call with no JavaScript
+fallback. Three canonical migrations are new since the last published
+`0.90.0-m7.12` package, so a site upgrading from that baseline is missing all
+three:
+
+| File | Adds |
+| --- | --- |
+| `20260904090000_c54603f8-a155-40f8-a86c-54434aa5c0ae.sql` | restates the `draft` default, records the `pages.status` column semantics at that migration step, and adds two partial `pages` indexes: one on `key` for undeleted status-published rows, one on `status`/`updated_at` for undeleted rows |
+| `20260904140000_9f2a7c41-06d5-4d6b-8b4e-1c7a5d3e9b20.sql` | `page_publications` — the row that decides what is public — the backfill for pages that were already live, and the first transactional page functions |
+| `20260904160000_0d565000-2839-4738-aacc-537d7090398f.sql` | the rest of the transactional page lifecycle: reveals, trash, restore and cancellation, plus two repair `UPDATE`s |
+
+The last two are the contract-v2 publication pair: they are what
+`PLATFORM_CONTRACT_VERSION = 2` means. All three are in the canonical schema
+manifest, though, so `missingMigrations` and `compareSchema` report every one
+that has not been applied — applying only the pair still leaves the schema out
+of sync. Go out in this order, and not in another:
+
+1. Apply every missing canonical migration. Upgrading from `0.90.0-m7.12`, that
+   is all three files above, in chronological order.
+2. Deploy the package and the site pinned to v2.
+3. Verify both: `missingMigrations(applied)` is empty, and
+   `assertPlatformContract(2)` passes. The second compares two version numbers
+   in the site's own code and never reads the database, so it is no substitute
+   for the first.
+4. Let editors back in.
+
+The migrations are designed to be applied before the v2 package is deployed,
+and the still-running m7.12 package remains compatible during that ordered
+rollout. They are not pure DDL and not function-only: the set carries an
+`ALTER … SET DEFAULT`, indexes and a column comment, a backfill `INSERT`, two
+repair `UPDATE`s scoped to pages already in the trash, and new and replaced
+functions. Nothing is deleted, and no page that is public before the upgrade
+stops being public because of it.
+
 ## 3. Apply the canonical schema
 
 The package ships the canonical migrations under `migrations/`, oldest first.

package/docs/PAGES.md

@@ -0,0 +1,452 @@
+# Pages: draft, published, duplicated
+
+## Draft is the default, everywhere
+
+A page that has just been created — or just been duplicated — is a **draft**.
+Nothing about it is on the public internet until somebody publishes it
+deliberately.
+
+That default is declared in three places that have to agree, and they are listed
+here because getting one of them wrong is the failure mode that leaks an unfinished
+page:
+
+| Layer | Where |
+| --- | --- |
+| Database default | `ALTER TABLE public.pages ALTER COLUMN status SET DEFAULT 'draft'` |
+| Server | `DEFAULT_PAGE_STATUS` in `src/cms/page-status.ts`, applied in `pages-core.ts` |
+| Public read | `page_publications` — an open publication window, and nothing else, makes a page public |
+
+Path resolution is deliberately status-blind: `resolvePathCore` answers with a
+page key for a draft too, because the same map serves the backoffice preview.
+The refusal happens one step later, in the public route's loader. If the
+published-page query answers with nothing — draft, scheduled but not yet open,
+or soft-deleted — the loader throws `notFound()`.
+
+That ordering is the point. `head()` is built from `loaderData`, so a loader
+that throws means the page's title, description and canonical URL are never
+emitted; without the refusal the route answered `200` with an empty body under
+a draft's own SEO. `sitemap.xml` never lists the page either, because it asks
+the same question of the same rows.
+
+Knowing the URL gets a visitor a 404.
+
+## One rule decides what is public
+
+`src/cms/page-publication.ts` holds it, in a sentence:
+
+> the newest active publication whose `publishAt` has arrived governs, and the
+> page is public while that row's `unpublishAt` has not.
+
+`pages.status` is **not** consulted by the public read. It records editorial
+intent — is this page finished? — and a finished page is not thereby public: a
+version scheduled for next week, a countdown target waiting for its deadline and
+a page whose window has closed are all finished and all hidden.
+
+Two things used to answer the question, and they disagreed in every direction
+that matters. A public read that fell back to `pages.status` served a countdown
+target the moment the countdown went up rather than at the deadline; it served a
+version scheduled for next week immediately; and `unpublish_at` hid nothing at
+all on a page that had already been published once. The fallback is gone.
+
+### The screens say what a visitor gets
+
+If `pages.status` does not decide what is public, an admin screen that shows only
+`pages.status` is telling the editor something that is not true. Both screens now
+show the state the rule produces — `publicationStateAt` over the page's own
+`page_publications` rows — in five words an editor can act on:
+
+| State | Badge | Means |
+| --- | --- | --- |
+| `draft` | Hidden | Nothing open, nothing scheduled |
+| `scheduled` | Scheduled to publish | Hidden now; a window opens later |
+| `published` | Published | A visitor can open it right now |
+| `ending` | Scheduled to hide | Public, with an end date already set |
+| `expired` | Hidden after expiry | Was public; the window has closed |
+
+`pages.status` is still shown, labelled **Editorial** so it cannot be mistaken
+for the other one, and the action offered follows the publication state rather
+than the status: a page reading `Published` offers Unpublish even when its status
+says `draft`, and an expired page offers Publish even when its status says
+`published`.
+
+### Where it is now, and what happens next, are two questions
+
+The five states above answer only the first one. A page that is live today and
+has a newer version scheduled for Friday is `published` — a visitor can open it
+right now — and a badge that stopped there would say nothing about Friday. A
+badge that instead read `Scheduled to publish` would be worse: it would claim the
+page is hidden.
+
+So the next boundary is derived separately, by `nextPublicationTransition`, which
+answers *when* and *which of three things*:
+
+| Kind | Happens at that instant |
+| --- | --- |
+| `publish` | A page that is hidden now becomes public |
+| `replace` | A page that is public now starts serving a different version |
+| `hide` | A page that is public now stops being reachable |
+
+`publicationSummary` composes the two into what the badge says, so
+`published` + `replace` reads **Published — update scheduled** and shows the
+handover time, while `ending` + `hide` still reads `Scheduled to hide`. The
+publication list marks the row that takes over as **next** —
+`publication_next_version_id`, the version that transition installs — so it is
+clear which of several queued rows is the one about to happen.
+
+Both confirmations follow the transition rather than the state.
+`PUBLISH_OVER_REPLACEMENT_CONFIRMATION` warns that publishing now makes the
+current draft visible immediately *and cancels that update*;
+`UNPUBLISH_OVER_SCHEDULE_CONFIRMATION` warns that unpublishing also cancels a
+publication already scheduled, which will not happen by itself afterwards. A
+host that has not started sending `publication_transition` yet still gets the
+right wording: `statusChangeConfirmation` falls back to the publication state.
+
+A screen left open crosses these boundaries without anybody touching it. Both
+screens arm a timer for the soonest boundary they can see and refetch when it
+passes, so a page goes from `Scheduled to publish` to `Published` in front of the
+editor rather than at the next navigation. `boundaryTimeoutMs` clamps the wait to
+six hours, so a boundary three months out costs one timer rather than a
+`setTimeout` overflow, and re-arms until it arrives.
+
+The awkward part is what happens *at* the boundary, and it is why both screens
+call one hook — `usePublicationBoundaryRefresh` — instead of keeping a timer each.
+The boundary is a fact about the server's data and the refresh is asynchronous, so
+between asking for fresh data and receiving it `boundaryTimeoutMs` keeps answering
+zero: the boundary really has passed, and it goes on having passed until a new
+`publication_at` arrives. Re-arming on that zero is a refetch loop with no delay in
+it, for as long as the answer takes and forever if the read fails. So the hook owns
+a chain of timers rather than a dependency on its own state. Once a refresh has
+been asked for, the next attempt waits `boundaryRetryMs` — thirty seconds, doubling
+to a five-minute ceiling — and what re-arms the timer at its natural length is a
+*new* boundary arriving in fresh data. Hitting the six-hour clamp is not an attempt
+at anything, so it refetches and starts the wait over rather than counting against
+the backoff.
+
+### Cancelling a schedule is not unpublishing
+
+The Cancel button on a publication row is offered only for a row that has not
+started, and the server decides that, not React. `cms_cancel_page_publication`
+locks the row and compares `publish_at` against the database clock: a row already
+started is refused with a message that names Unpublish as the thing to use
+instead, because cancelling it would take the page off the public website —
+possibly putting an older version back — under a word that promises the opposite.
+A row that is already inactive answers `already-cancelled` and writes nothing, so
+a second click is not an error. A cancellation that goes through retires exactly
+that row, audits it as `page.schedule.cancel`, and leaves what visitors can reach
+untouched.
+
+That check is against `now()` on the server, so a screen rendered a minute before
+the boundary and clicked a minute after it is refused rather than obeyed. Live
+rows do not offer the button at all; they carry the sentence *Live — unpublish
+the page to take it down*.
+
+`listPagesCore` and `getPageForEditCore` read those rows, so the derivation
+happens once on the server rather than three times in three components. A
+`page_publications` read that fails is an error, not an empty list — a page
+silently reported as `Hidden` because a query failed is the same lie in the other
+direction.
+
+The second half of the rule — *that row's* `unpublishAt` — is why an older row
+never comes back into force behind a newer one. Without it, "hide this at
+midnight" would quietly mean "show the previous version again at midnight".
+
+Boundaries are exact. A page is public **at** its `publish_at` and hidden **at**
+its `unpublish_at`, to the millisecond, and
+`tests/page-publication-window.test.ts` pins all five positions — before, at the
+start, inside, at the end, after — through the pure rule, the page reader and
+the sitemap alike.
+
+Caches inherit the boundary rather than outliving it. `getPublishedPageCore`
+returns `revalidateAt`, the next instant its answer can change; the server cache
+expires an entry at that instant when it comes before the TTL, and the browser
+query's `staleTime` is clamped the same way. A twenty-second cache can no longer
+carry a 404 five seconds past the moment a page goes live.
+
+### The migrations, and the order they go out in
+
+Three files are new since the last published `0.90.0-m7.12` package, so a site
+upgrading from that baseline is missing all three:
+
+| File | Adds | Needed for |
+| --- | --- | --- |
+| `20260904090000_c54603f8-a155-40f8-a86c-54434aa5c0ae.sql` | restates the `draft` default, records the `pages.status` column semantics at that migration step, and adds two partial `pages` indexes: one on `key` for undeleted status-published rows, one on `status`/`updated_at` for undeleted rows | canonical schema parity |
+| `20260904140000_9f2a7c41-06d5-4d6b-8b4e-1c7a5d3e9b20.sql` | `page_publications`, the backfill, `cms_save_page_version`, `cms_set_page_status`, `cms_schedule_page_reveal` | contract-v2 publication behaviour |
+| `20260904160000_0d565000-2839-4738-aacc-537d7090398f.sql` | reveals and audit metadata inside `cms_save_page_version`, `cms_soft_delete_page`, `cms_restore_page`, `cms_cancel_page_publication`, `cms_schedule_page_version`, and two repair `UPDATE`s | contract-v2 publication behaviour |
+
+The last two are the pair that establishes contract-v2 publication behaviour:
+together they are what `PLATFORM_CONTRACT_VERSION = 2` means. A site declares the
+contract it was built against and `assertPlatformContract` refuses the mismatch
+at startup, rather than letting an editor discover it when a publish fails
+halfway.
+
+All three are listed in `SCHEMA_MIGRATIONS`. `compareSchema` names whichever of
+them is missing and does not report in sync until every canonical migration has
+been applied, so applying only the publication pair leaves the drift check
+pointing at the first file.
+
+Release order, and it is not interchangeable:
+
+1. **Apply every missing canonical migration.** Upgrading from `0.90.0-m7.12`,
+   that is all three files above, in chronological order. They add a column
+   default, indexes and a comment, a table, functions and replaced function
+   bodies, and the running m7.12 package keeps working against them. They are
+   not, however, pure DDL: the second backfills an open publication for every
+   published page that has none, and the third runs two repair `UPDATE`s over
+   rows the old code left inconsistent — retiring publications still open on
+   pages already in the trash, and setting those pages' status back to `draft`.
+   Both are described below. Nothing is deleted and no page that is public
+   before the upgrade stops being public because of it.
+2. **Deploy the contract-v2 package.** It calls the new signatures, which by then
+   exist.
+3. **Verify both.** `compareSchema` reports in sync — no canonical migration
+   missing — and `assertPlatformContract(2)` returns. The second compares two
+   version numbers in the site's own code and never reads the database, so on
+   its own it says nothing about whether the migrations ran.
+4. **Let editors back in.**
+
+Deploying the package first gives an editor a publish that fails on a function
+that is not there yet; that is the click-time failure this ordering exists to
+avoid.
+
+The `…140000_…` file backfills an open publication for every published page that
+has none, so a site that was live before the upgrade is still live after it.
+
+The `…160000_…` file repairs what the trash left behind, in two `UPDATE`s over
+existing rows. A page deleted before this migration kept its open publication —
+unreachable, because the reader skips deleted pages, but waiting for the restore
+button to make it public again — so those rows are retired. And those same pages
+often still said `published` in a list, a claim about the public website that
+stopped being true when they were deleted, so their status goes back to `draft`.
+Both statements touch only pages with `deleted_at` set: nothing a visitor can
+reach today changes.
+
+It deliberately skips a page that already has an active row: that row is a deliberate schedule —
+a countdown reveal, a dated launch — and publishing it now is exactly the bug
+being fixed. A published page whose window has already closed goes dark, because
+that is what its editor asked for.
+
+## Publishing is one transaction
+
+Publishing is five statements: write the version, move `current_version_id`,
+retire the old publication, open the new one, flip the status. A PostgREST
+client cannot wrap them, and checking each response is not a fix — it reports the
+failure honestly and leaves the site half published either way. An open
+publication with the status never flipped made a page public that the editor was
+told had not published; a moved current-version pointer with the replacement
+publication missing put the next draft in front of visitors.
+
+So the whole change lives in the database:
+
+| Function | Called by |
+| --- | --- |
+| `cms_save_page_version` | `savePageVersionCore` |
+| `cms_set_page_status` | `setPageStatusCore` |
+| `cms_schedule_page_reveal` | `cms_save_page_version`, and the countdown path |
+| `cms_soft_delete_page` | `deletePageCore` |
+| `cms_restore_page` | `restorePageCore` |
+
+Each is `SECURITY DEFINER` with the same staff check as every other page
+mutation, and each writes its audit row inside the same transaction — a
+publication nobody can account for afterwards is its own half-applied write.
+
+Countdown reveals are inside that transaction too, and that is the second half of
+the fix. Scheduling them afterwards meant a reveal that could not be scheduled —
+a target renamed, or never written to — reported a failed publish to an editor
+whose page was already live. `savePageVersionCore` now reads the reveal
+instructions out of the blocks *before* it calls anything and passes them in as
+`_reveals`; the source page, every reveal and every audit row commit together or
+not at all. `_audit` carries the actor's own metadata into the `page.publish`
+row written by the same statement.
+
+There is deliberately **no JavaScript fallback**. Compensating for a failed step
+with further un-transacted steps is precisely the thing that does not work.
+
+`tests/page-publish-duplicate.test.ts` breaks each statement in turn and then
+asks the public reader what it serves; the answer has to be exactly what it was
+before the call. `tests/page-publish-atomicity.test.ts` does the same for the
+reveals — the only schedule, the second of several, the publication audit — and
+checks the database rows as well as the public answer, because "nothing visible
+changed" and "nothing changed" are different claims.
+
+## Deleting is not unpublishing, and restoring is not publishing
+
+The trash used to leak in both directions. `deletePageCore` set `deleted_at` and
+left the publication rows active; `restorePageCore` cleared `deleted_at` and
+those rows came back into force. Publish, trash, restore, and the page was on the
+internet again — a publishing action nobody confirmed, from a button labelled
+Restore.
+
+Both halves are now one statement each:
+
+- **`cms_soft_delete_page`** retires every active publication, sets `deleted_at`
+  and sets `status` to `draft`, in one transaction. A page in the trash is off
+  the internet by the same rule that governs every other page, not by a second
+  rule that happens to agree.
+- **`cms_restore_page`** clears `deleted_at` and leaves the page a hidden draft.
+  It never inserts a publication and never reactivates one — including the rows a
+  page deleted before this migration still carries, which it retires on the way
+  through. A restored page becomes public when somebody presses Publish.
+
+`tests/page-trash-restore.test.ts` walks it: publish, delete, restore,
+`getPublishedPageCore` answers `null`, `listPublishedPageKeysCore` omits the key,
+and only an explicit publish puts it back.
+
+## Granting EXECUTE on a self-hosted server
+
+The functions are `SECURITY DEFINER`, so PUBLIC is revoked unconditionally — on
+every server, with or without the hosted roles. `anon`, `authenticated` and
+`service_role` are PostgREST deployment conventions; naming a role that does not
+exist is an error rather than a warning, so those grants run only when the role
+is there. Existing hosted installations are unaffected: `authenticated` and
+`service_role` keep EXECUTE, `anon` gets nothing.
+
+A self-hosted installation grants its own application role, in a migration of its
+own. Every statement, in full:
+
+```sql
+GRANT EXECUTE ON FUNCTION
+  public.cms_save_page_version(uuid, jsonb, text, boolean, text, jsonb, jsonb) TO cms_app;
+GRANT EXECUTE ON FUNCTION public.cms_set_page_status(uuid, text, jsonb, text)  TO cms_app;
+GRANT EXECUTE ON FUNCTION
+  public.cms_schedule_page_reveal(text, timestamptz, jsonb, text, uuid, timestamptz) TO cms_app;
+GRANT EXECUTE ON FUNCTION
+  public.cms_schedule_page_version(uuid, timestamptz, timestamptz, text, jsonb, jsonb, text) TO cms_app;
+GRANT EXECUTE ON FUNCTION public.cms_cancel_page_publication(uuid, jsonb, text) TO cms_app;
+GRANT EXECUTE ON FUNCTION public.cms_soft_delete_page(uuid, jsonb, text)       TO cms_app;
+GRANT EXECUTE ON FUNCTION public.cms_restore_page(uuid, jsonb, text)           TO cms_app;
+```
+
+`cms_actor_email` is deliberately absent. It is an internal helper the writers
+call for themselves, and nothing outside them needs it.
+
+## Proving it against a real server
+
+The unit tests run all of this against a fake PostgREST client. That proves the
+TypeScript, not the SQL: whether the functions parse, keep the signatures the
+client calls, grant legally on a server without the hosted roles, and really do
+roll a half-finished publish back. Only a server answers those.
+
+```bash
+bun run test:migrations
+```
+
+It starts a disposable `postgres:16-alpine` container, applies every migration to
+two databases and makes 103 assertions:
+
+- **neutral** — the hosted roles are dropped from the cluster *before* the two
+  publication migrations run. Both apply; PUBLIC can execute none of the seven
+  writers; a freshly created application role granted by the statements above
+  can execute all seven, and still not `cms_actor_email`.
+- **legacy** — every migration in order on a database that has the hosted roles.
+  Signatures are checked against what the client calls, `authenticated` and
+  `service_role` keep EXECUTE, `anon` has none.
+- **behaviour** — a publish with a reveal; then a trigger that refuses the
+  publication audit, and another that refuses the reveal *after* the source page
+  has been published, each of which has to leave the database exactly as it was;
+  then delete, restore, and the explicit publish that finally puts the page back.
+- **guards** — the refusals, which are worth as little as the server that
+  enforces them: restoring a page that is not in the trash; a countdown aimed at
+  the page carrying it, at a page already public, or at a deadline that has
+  already passed; several reveals of which one is impossible; cancelling a
+  scheduled publication, and being refused when it has already started; and the
+  times `cms_schedule_page_version` will and will not accept. Each refusal is
+  followed by a check that the publication rows, the pages and the sitemap are
+  byte-for-byte what they were before it.
+
+`ops/migration-smoke/prelude.sql` supplies the `auth` and `storage` stubs a plain
+server does not have. It is not shipped and is not a migration — it exists so the
+real migrations can be run against something.
+
+### Pointing it at a server of your own
+
+```bash
+CMS_SMOKE_ALLOW_DESTRUCTIVE=1 CMS_SMOKE_DSN=postgres://… bun run test:migrations
+```
+
+`CMS_SMOKE_DSN` skips Docker, which is what CI's `migrations` job does with a
+`postgres:16` service. **It requires a disposable PostgreSQL cluster.** The
+runner creates and drops databases, and it drops and recreates the cluster-wide
+roles `anon`, `authenticated` and `service_role` — by those names, because the
+migrations grant to them by those names, so they cannot be renamed per run.
+Against a shared or production server that is an outage, which is why a DSN
+without `CMS_SMOKE_ALLOW_DESTRUCTIVE=1` refuses to run at all rather than
+starting and stopping halfway. The container form needs no acknowledgement: it
+creates the server it destroys.
+
+Everything else the run names for itself carries a random suffix —
+`cms_smoke_neutral_…`, `cms_smoke_legacy_…`, `cms_smoke_app_…` — so a crashed run
+leaves debris that is recognisably this script's, and the next run clears it
+before it starts. Only that naming is ever touched. `CMS_SMOKE_KEEP=1` keeps
+them, and the container, around to poke at.
+
+The job is deliberately not part of `bun run check`, which must keep running with
+nothing but Bun installed.
+
+## Publishing is a confirmed action
+
+One click never publishes, from either screen that can.
+
+The Pages list opens a dialog whose text is fixed in `src/cms/page-status.ts` so
+it cannot drift between screens:
+
+```ts
+PUBLISH_CONFIRMATION   // "This will make the page visible to everyone on the internet…"
+UNPUBLISH_CONFIRMATION // "Visitors will no longer be able to reach this page…"
+```
+
+The dialog names the page and its address (`About us — /about`), so the last thing
+an editor reads before publishing is *which* page they are publishing. Escape and
+Cancel change nothing; the tests assert the mutation was **not called**, rather
+than that a dialog closed.
+
+`ConfirmDialog` handles the accessibility: `role="dialog"`, `aria-modal`,
+`aria-labelledby` on the heading, `aria-describedby` on the confirmation text,
+initial focus on the confirm button, Tab trapped inside, focus restored on close.
+
+The page builder's **Publish now** sits in the same button row as **Save draft**
+and is the other way a page goes live, so it confirms too — with the same native
+`confirm()` its neighbours in that screen already use for cancelling a scheduled
+publication and restoring a version. It names the page. Declining calls nothing;
+the test asserts `save` was not invoked, not that a dialog closed.
+
+Unpublish is styled `bg-red-600`. Publish is not. The destructive-looking one is
+the one that takes something away from visitors.
+
+## Duplication
+
+Duplicating asks for a name first, because the copy is going to sit next to the
+original in a list and "About us (copy)" is only useful for about a minute.
+
+- The address is derived from the name (`slugifyPageKey`) and made unique
+  (`uniquePageKey`), so `about-us` becomes `about-us-2`.
+- Once the editor edits the address themselves, it **stops** following the name.
+  A field that keeps overwriting what you typed is worse than no suggestion.
+- The copy is a deep copy with fresh block ids throughout
+  (`duplicateBlockTree`), so editing the copy cannot reach into the original.
+- **No canonical URL is duplicated.** The copy is built from a deliberately
+  narrow `select` — key, name and the current version's blocks — so canonical
+  URLs, slugs and meta titles are never carried across. They are per-page facts,
+  and two pages claiming the same canonical is a silent search-ranking bug.
+- `is_system` is `false` on the copy, whatever the original was. A duplicate of
+  a system page is ordinary content.
+- The copy is a draft. Always.
+
+The dialog states both of those last two facts in words — "the copy is a draft"
+and "the original is not changed" — because that is the question an editor
+actually has before pressing the button.
+
+## Host wiring
+
+Both actions are **optional** on the host contract:
+
+```ts
+pages: { fns: {
+  setPageStatus?: HostServerFn;
+  duplicatePage?: HostServerFn;
+} }
+```
+
+A host that has not registered them keeps working — the Pages list hides the two
+actions rather than offering a button that throws. Authorization is the existing
+one: both go through the same staff guard as every other page mutation, and
+`tests/page-publish-duplicate.test.ts` pins a non-staff caller being refused.

package/docs/SCHEDULING.md

@@ -0,0 +1,130 @@
+# Scheduled visibility
+
+One question — *should this be on screen right now?* — is answered in one place,
+`src/cms/visibility-schedule.ts`. Menu items, footer columns and footer links all
+call the same function with the same clock. Nothing re-implements the comparison,
+because two implementations of "is it visible yet" drift, and the drift is
+invisible until a customer sees a menu entry that the footer says is gone.
+
+## The shape
+
+```ts
+type VisibilitySchedule = {
+  enabled?: boolean;      // the manual switch; absent means shown
+  publishAt?: string | null;   // ISO-8601 UTC instant, or absent
+  unpublishAt?: string | null; // ISO-8601 UTC instant, or absent
+};
+```
+
+An item with no schedule at all is visible. That is the important default: this
+feature was added to a site that already had menus, and none of those rows have
+a `schedule` key. `isVisibleAt(undefined, now)` is `true`, so nothing disappeared
+on upgrade.
+
+`normalizeSchedule` **omits** keys rather than writing `null` for them, so a
+schedule that has never been given a date round-trips through JSONB as `{}`
+instead of accumulating null fields on every save.
+
+## Storage is UTC. Display is the site's timezone.
+
+The stored value is always a UTC instant. The editor never sees one.
+
+`ScheduleField` (`src/backoffice/ScheduleFields.tsx`) is the only place the
+conversion happens, in both directions:
+
+| Direction | Function | Example |
+| --- | --- | --- |
+| Editor types → stored | `localInputToIso` | `2026-09-10T18:00` in `Europe/Stockholm` → `2026-09-10T16:00:00.000Z` |
+| Stored → editor sees | `isoToLocalInput` | the same instant back to `2026-09-10T18:00` |
+
+The zone comes from `siteTimezone()` (`src/config/site-config.ts`), not from the
+administrator's laptop. An editor in Madrid scheduling a Swedish site's banner
+gets Swedish opening time, which is what they meant.
+
+`src/cms/timezone.ts` does the offset arithmetic with `Intl.DateTimeFormat` —
+no date library was added. `zoneAbbreviation` puts `CEST` next to the fields so
+the editor can see which clock they are on.
+
+## The one rule that matters
+
+**Do not call `Date.now()` inside a render path that shows scheduled content.**
+
+`renderableNavigation(items, locale, now)` takes the instant as a parameter. So
+does `visibleItems`, `isVisibleAt` and `visibilityStateAt`. This is not test
+convenience — it is what makes a boundary *reachable*. A component that reads the
+clock itself renders once, caches, and then shows yesterday's menu until
+something unrelated re-renders it.
+
+`useScheduleClock` (`src/cms/use-schedule-clock.ts`) closes that loop: give it the
+schedules on screen and it re-renders at the next boundary and no sooner. Not a
+one-second interval — `nextScheduleChangeAcross` computes the single next instant
+anything changes, and a page with no schedules never sets a timer at all.
+
+```tsx
+const now = useScheduleClock(navigationSchedules(items));
+const visible = renderableNavigation(items, locale, now);
+```
+
+## What an editor sees
+
+`VisibilityBadge` renders six states, each with a word and an icon shape as well
+as a colour: **Visible**, **Hidden**, **Scheduled to publish**, **Scheduled to
+hide**, **Expired**, **Needs attention**. Status is never colour alone.
+
+Two kinds of nonsense are refused rather than stored.
+
+`scheduleProblems` names a range that ends before it starts. `zonedLocalExists`
+catches the other one: a wall-clock time the site's timezone never reaches.
+Typing `2026-03-29T02:30` for a Stockholm site would resolve to an instant an
+hour from what was typed, because the clocks jump 02:00 → 03:00 that night, so
+`ScheduleField` keeps the field's previous value and says why instead. In both
+cases the offending field takes `aria-invalid` and the message is tied to it
+with `aria-describedby`.
+
+Autumn's *repeated* hour is deliberately allowed. `01:30` happens twice, so both
+readings are real instants and taking the first is a defensible answer; the
+spring gap has no reading at all.
+
+`ScheduleField` is a controlled input, though, and the Save button belongs to
+whichever screen embeds it. So the refusal cannot end at the field — two places
+make it binding:
+
+- `saveContentSectionCore` runs `scheduleProblemsIn` over the whole content
+  payload before writing and rejects the save, naming the path of the first bad
+  schedule (`columns[0].links[2].schedule`). Menus, footers and shared sections
+  all save through it, so a host cannot store an invalid schedule by forgetting
+  to wire the field's validity into its own button.
+- The page builder checks the schedule panel's own fields before it saves
+  anything, because that button is the platform's.
+
+The page builder reads those fields in `siteTimezone()` too, not in the
+browser's zone — an editor on a laptop still set to New York schedules the same
+instant as a colleague at home.
+
+## Pages schedule through publications, not through this
+
+Everything above is about *items inside a page* — menu entries, footer links,
+sections. A whole page's visibility is a different mechanism with its own rows:
+`page_publications`, one rule in `src/cms/page-publication.ts`, described in
+[`PAGES.md`](PAGES.md).
+
+They are deliberately not merged. A page's schedule has to be readable by the
+sitemap and by the public route without loading the page's content first, and it
+has to survive a version being replaced underneath it. A JSONB `schedule` key on
+a content row answers neither.
+
+What they share is the vocabulary. `publishAt` and `unpublishAt` mean the same
+thing on both sides, both store UTC instants and display the site's timezone,
+and both are closed **at** `unpublishAt` rather than a tick later. An editor
+unpublishing a page still gets it gone now: `setPageStatusCore` closes every open
+window as well as setting the status, so a page cannot stay live through a
+schedule somebody forgot about. Moving a page to the trash closes them too, and
+restoring it does not reopen them — see
+[Deleting is not unpublishing](PAGES.md#deleting-is-not-unpublishing-and-restoring-is-not-publishing).
+
+They also share the five words for what a schedule is currently doing. A page's
+badge comes from `publicationStateAt` — Hidden, Scheduled to publish, Published,
+Scheduled to hide, Hidden after expiry — for the same reason an item's comes from
+`visibilityStateAt`: "draft" and "published" cannot say which side of a window
+something is on, and that is the only thing an editor looking at a schedule wants
+to know.