@bygghammar/cms-platform 0.90.0-m7.8 → 0.91.0-m7.1

package/CHANGELOG.md

@@ -8,6 +8,303 @@ 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-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
+  administrator told only that "passwords are stored as server secrets" does the
+  one thing the sentence was meant to prevent and pastes the password into the
+  CMS field in front of them, so the screen names the configuration file, the
+  environment-variable names and the secret-name convention for that
+  installation instead. It stays value-free: no secret is read, returned or
+  rendered, and hosts supply their own deployment root through
+  `secretsLocation` — including `/`, which stays absolute.
+- Optional block content whose localized value is empty is no longer rendered.
+  A heading or paragraph written in one locale and left blank in another used to
+  leave its empty markup behind in the locale that had nothing to say.
+- Nested navigation items are editable. Only top-level entries could be changed,
+  so fixing a typo in a child link meant deleting it and building it again.
+- Rich text holds up at length, and a block chooses how it appears. Each block
+  carries its own reveal mode; `Reveal` still defaults to `fade`, so every
+  already-published page looks exactly as it did.
+- Cooperative editing locks stop two administrators overwriting each other. A
+  lock is taken when an editor opens a resource, renewed while it stays open and
+  released when it closes, and a second editor is told who holds it instead of
+  silently losing the earlier write. Pages, global sections, shared content,
+  navigation, contact details, forms, form defaults, form history and page SEO
+  are covered, and the refusal is enforced in the server cores — not only by
+  disabling controls in the interface.
+- The lock's session token is private and the session match is exact.
+  `session_id` is never returned by any read: authenticated callers hold column
+  grants that omit it, the JSON shape drops it, and the administrator listing
+  returns a redacted row. A write against a live lock succeeds only for the
+  exact, non-empty session that holds it. Empty or malformed lock responses fail
+  closed rather than reading as "free", a stale asynchronous reply cannot revive
+  a lock that was already released, reopening an editor can no longer let its
+  own release overtake its next acquire, and a duplicated browser tab is given
+  its own session identity — Web Locks where the browser provides them, a
+  best-effort BroadcastChannel fallback where it does not.
+- Lock storage is a host port, not a provider. `editLockActionCore` and
+  `assertEditable` reach the database only through `EditLockAdapter`
+  (`@bygghammar/cms-platform/server/edit-lock-adapter`) — five methods covering
+  acquire, status, release, list and the staff check — so an application on
+  ordinary PostgreSQL implements it with the SQL it already writes, with no
+  PostgREST client and no `supabase` object to imitate. Hosts that already build
+  `{ supabase: { rpc }, userId, claims }` for their other cores keep passing
+  exactly that: `createSupabaseEditLockAdapter` is applied for them
+  automatically and nothing on an existing host changes.
+- Locks require a migration and host wiring, and change nothing until both are
+  done. `migrations/20260902090000_dc072b25-8467-46ae-aef3-0ccdf40aa7eb.sql`
+  creates the table and its functions; `docs/EDIT-LOCKS.md` is the host
+  contract: one authenticated server endpoint through `editLockActionCore`, one
+  `EditLockProvider` built with `createEditLockApi`, the non-empty
+  `editSessionId` forwarded to every protected write, `pageKey` passed to
+  `PageSeoPanelView`, and the `edit_locked:` message prefix preserved across the
+  host's own transport. Until then every screen behaves exactly as it did before
+  locks existed.
+- The lock is a cooperative server preflight, not a transaction-atomic write
+  fence. The check and the mutation are separate statements, so a host needing
+  strict exclusion must put both in one transaction or RPC. Full-document exits
+  deliberately let the lock lapse by TTL — 120 seconds by default — rather than
+  race a reload against its own release.
+- Verified on PostgreSQL 16 and 17: the migration applies in a single
+  transaction against a throwaway container carrying a host's real role,
+  authentication and user objects; the grants, the RLS policy and the
+  `SECURITY DEFINER` `search_path` come out as written; twenty simultaneous
+  acquires of one resource leave exactly one holder and no errors; and a
+  shadowing `pg_temp` object cannot reach inside a definer body.
+- Not verified in this release: the migration has not been applied to any real
+  staging or production database, and the two-user real-browser lock behaviour
+  has not been exercised against a live host. Both remain required before
+  production use.
+
 ## 0.90.0-m7.8
 
 - Requires `@bygghammar/lightweight-popup@>=0.2.0-m7.8`. `m7.6` and `m7.7` were

package/README.md

@@ -25,6 +25,33 @@ apply the canonical schema with `bunx cms-platform-migrations`, import
 `theme.css`, register host components / platform data / translations, wrap the
 server cores and mount the shared backoffice views.
 
+## Editing locks
+
+`docs/EDIT-LOCKS.md` is what a host wires so two administrators cannot
+overwrite each other: run the migration, expose one server endpoint through
+`editLockActionCore`, mount `EditLockProvider` with `createEditLockApi`, and
+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.
@@ -32,7 +59,10 @@ server cores and mount the shared backoffice views.
   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.
 
@@ -119,8 +149,14 @@ bun run check   # typecheck + tests + package verification
 
 The package ships TypeScript sources; there is no build output. Every change
 goes through a pull request, and every release is triggered by pushing a
-`vX.Y.Z` tag that matches `package.json`, which publishes to npm from GitHub
-Actions using the repository secret `NPM_TOKEN`. Never publish manually.
+`vX.Y.Z` tag that matches `package.json`. That tag runs
+`.github/workflows/publish.yml`, which publishes to npm using **Trusted
+Publishing**: GitHub mints a short-lived OIDC token scoped to that single
+workflow run, and npm exchanges it for publish rights through the package's
+Trusted Publisher configuration. No long-lived npm credential takes part — no
+`NPM_TOKEN`, no `NODE_AUTH_TOKEN`, no OTP. [RELEASING.md](./RELEASING.md) is
+what the workflow checks and the npm settings it has to match. Never publish
+manually.
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full workflow and changelog
 conventions. Consumers install an explicit released version such as

package/docs/EDIT-LOCKS.md

@@ -0,0 +1,213 @@
+# Editing locks: what a host has to wire
+
+Two administrators opening the same page used to be a silent race — whoever
+saved last won, and the other one's work disappeared without a message. The
+lock makes that a refusal instead: the second person sees who has the page and
+cannot type into it, and the server refuses the write even if they try.
+
+The package supplies all of it except three connections only the host can make.
+Until they are made every screen behaves exactly as it did before locks
+existed, which is what lets an installation upgrade the package first and the
+database afterwards.
+
+## 1. Run the migration
+
+`migrations/20260902090000_dc072b25-8467-46ae-aef3-0ccdf40aa7eb.sql` creates
+`public.cms_edit_locks` and five functions. It is safe to run more than once.
+It is ordinary PostgreSQL — a table, an index, grants, one RLS policy and four
+`SECURITY DEFINER` functions with a pinned `search_path`. A host that stores
+locks some other way can skip it and supply its own adapter instead; see
+[Storage](#storage).
+
+Until it runs, `assertEditable` sees "no such function" and lets every write
+through — an upgrade cannot break saving. After it runs, the server checks are
+available; the provider and save-path forwarding below are still required for
+per-tab UI locking.
+
+## 2. One server endpoint
+
+Every lock call goes through `editLockActionCore`, so the host writes one
+server function rather than five:
+
+```ts
+import { editLockActionCore, isEditLockAction } from "@bygghammar/cms-platform/server/edit-locks-core";
+import { editLockSchemas } from "@bygghammar/cms-platform/server/schemas";
+
+export const editLock = serverFn(async ({ data }) => {
+  if (!isEditLockAction(data.action)) throw new Error("Unknown lock action");
+  const input = editLockSchemas.acquire.parse(data);
+  return editLockActionCore(await authContext(), data.action, input);
+});
+```
+
+`authContext()` returns the lock storage for the signed-in user — see
+[Storage](#storage) for what that is. The lock functions run as that user, so
+`is_staff` and RLS apply exactly as they do everywhere else.
+
+## 3. One provider in the browser
+
+```tsx
+import { useMemo } from "react";
+import { createEditLockApi, EditLockProvider } from "@bygghammar/cms-platform/backoffice/EditLock";
+
+const lockApi = useMemo(
+  () => createEditLockApi(
+    (action, input) => editLock({ data: { action, ...input } }),
+    { canSteal: isSuperadmin },
+  ),
+  [editLock, isSuperadmin],
+);
+
+<EditLockProvider api={lockApi}>{backoffice}</EditLockProvider>
+```
+
+Mount it once, around the backoffice. Every editing screen finds it by itself.
+Keep the API object stable with `useMemo`: its identity controls the editors'
+acquire/release effects, so rebuilding it during each render would repeatedly
+release and reacquire their locks.
+
+`canSteal` only decides whether the take-over button is *offered*; the database
+function refuses anyone but a superadmin regardless, so offering it to an
+ordinary editor produces a button that always fails.
+
+Leave the api `null` — or mount no provider at all — and every screen reports
+"not enforced" and behaves as before.
+
+## 4. Pass the session id on to the saves
+
+The provider is what shows the banner. The session id is what makes the server
+able to tell *this* editor's save from someone else's, and it travels with the
+save, not with the lock.
+
+Each screen already puts `lock.sessionId` into the deps it calls. The host's
+job is to forward it to the matching core:
+
+| Screen | Host dep | Core | Resource |
+| --- | --- | --- | --- |
+| `PageBuilderView` | `save`, `rename`, `schedule`, `cancelPublication`, `restoreVersion` | `savePageVersionCore`, `renamePageCore`, `schedulePageVersionCore`, `cancelPagePublicationCore`, `restorePageVersionCore` | `page` / page id |
+| `GlobalSectionBuilderView` | `save`, `rename`, `setKind` | `saveGlobalSectionVersionCore`, `renameGlobalSectionCore`, `setGlobalSectionKindCore` | `global_section` / section id |
+| `SectionEditorView`, `NavigationView`, `ContactDetailsView` | `save` | `saveContentSectionCore` | `content_section` / section key |
+| `FormEditorView` | `saveForm`; pass `editSessionId` into its host `VersionHistory` too | `saveFormCore`, `restoreFormVersionCore` | `form` / form id |
+| `FormSettingsView` | `saveDefaults`; forward the whole `data` object, or destructure its `editSessionId` into the core's third argument | `saveFormDefaultsCore` | `form_defaults` / `form_settings` |
+| `PageSeoPanelView` | `onSave(form, editSessionId)`, `onReset(editSessionId)` | `savePageSeoCore`, `deletePageSeoOverrideCore` | `page_seo` / `pageKey` |
+
+The cores and schemas accept `editSessionId` as an optional field so an
+unwired/unmigrated host keeps its old behaviour while no lock exists. Once a
+resource has a live lock, every protected write requires the matching session
+id, including writes by another tab of the same user. Forward it on every path
+in the table; omission is not a bypass.
+
+`PageSeoPanelView` additionally needs `pageKey`. Without it the SEO panel has
+no resource to lock and stays unlocked, even with everything else wired.
+
+## Storage
+
+`editLockActionCore` and `assertEditable` never touch a database themselves.
+Every read and write goes through `EditLockAdapter`
+(`@bygghammar/cms-platform/server/edit-lock-adapter`), five methods over the
+domain operations and nothing else:
+
+```ts
+type EditLockAdapter = {
+  assertStaff(): Promise<void>;
+  acquire(input: EditLockRef & { sessionId: string; ttlSeconds: number; steal: boolean }): Promise<EditLockState>;
+  status(input: EditLockRef & { sessionId: string | null }): Promise<EditLockState>;
+  release(input: EditLockRef & { sessionId: string }): Promise<boolean>;
+  list(): Promise<EditLockRow[]>;
+};
+```
+
+The context a core takes is `{ editLocks: <adapter> }`. Nothing in the contract
+names a driver, a client library or a wire format, so a self-hosted application
+on ordinary PostgreSQL implements it with the SQL it already writes:
+
+```ts
+import type { EditLockAdapter } from "@bygghammar/cms-platform/server/edit-lock-adapter";
+import { EditLockNotInstalledError } from "@bygghammar/cms-platform/server/edit-lock-adapter";
+import { asEditLockState } from "@bygghammar/cms-platform/cms/edit-lock";
+
+const MISSING = new Set(["42883", "42P01"]); // no such function, no such table
+
+export function editLockStorage(pool: Pool, userId: string): EditLockAdapter {
+  const query = async (text: string, values: unknown[]) => {
+    try {
+      return await pool.query(text, values);
+    } catch (error) {
+      if (MISSING.has(error.code)) throw new EditLockNotInstalledError();
+      throw error;
+    }
+  };
+  return {
+    async acquire(input) {
+      const { rows } = await query(
+        "SELECT public.cms_acquire_edit_lock($1, $2, $3, $4, $5) AS state",
+        [input.resourceType, input.resourceId, input.sessionId, input.ttlSeconds, input.steal],
+      );
+      return asEditLockState(rows[0]?.state);
+    },
+    // status, release, list and assertStaff in the same shape
+  };
+}
+```
+
+Two rules an adapter has to honour, whatever it is built on:
+
+- **`acquire` must be one atomic statement.** Two editors opening the same page
+  at the same instant have to contend on a single unique index so exactly one
+  wins. Read-then-write leaves a window in which both do.
+- **`sessionId` is a bearer token.** It goes in and is never returned. Knowing
+  another tab's session id is enough to save as its holder, so no read may
+  include it — not `status`, not `list`.
+
+Whether the storage runs on a stored function, plain SQL in the adapter, or a
+service of its own is the host's decision. A PostgREST-shaped host that already
+builds `{ supabase: { rpc }, userId, claims }` for its other cores can keep
+passing exactly that: `createSupabaseEditLockAdapter` is applied for it
+automatically, and the migration's functions are the storage.
+
+## What the server does with it
+
+`assertEditable` sits before each protected write. A write from another session
+throws `EditLockedError`. On the server it has `error.code === "edit_locked"` and
+`error.state`. TanStack Start serializes only an Error's message, so the message
+also begins with `edit_locked:` and `isEditLockedError()` recognises either
+form after transport. Do not replace that failure with a success response.
+
+This is a cooperative preflight lock, not a transaction-wide database fence.
+Expiry, a new acquisition, a superadmin steal, or an explicit release could
+land between the status preflight and a later PostgREST mutation. Strict
+transactional exclusion would require each mutation and its lock check in one
+database RPC, or a fencing token checked by the write itself.
+
+The per-tab session id is a bearer value and is never returned by a lock
+status/acquire response. Authenticated staff have column-level read access to
+the operational lock fields but not `session_id`; the administrative list RPC
+omits that column. This prevents a blocked browser from reading the
+holder's token and replaying it in a save.
+
+Modern browsers also hold an exclusive Web Lock for that bearer value before
+the first server acquire. This detects a duplicated tab even when the original
+is frozen. Browsers without Web Locks fall back to a short BroadcastChannel
+handshake. That fallback is best-effort because a frozen source tab can answer
+too late; without either primitive there is no duplicate-tab signal at all.
+Multi-user locking remains enforced in either case.
+
+## Choosing the lifetime
+
+A lock lasts 120 seconds by default and is renewed every 40. A browser that
+crashes therefore frees the page about two minutes later, with no cleanup job
+anywhere. Pass `ttlSeconds` to `createEditLockApi` to change it; the database
+clamps to 15–3600 whatever it is told.
+
+Leaving an editor through client-side navigation releases immediately. Closing
+or reloading the whole document relies on the TTL: firing a release from the
+old document can arrive after the reload has already reacquired with the same
+session and delete its new lock. A restored/backgrounded page stays fenced
+until its catch-up renewal confirms it still holds the resource.
+
+## Recovering a stuck lock
+
+`listEditLocksCore` returns every live lock, and `steal` takes one — superadmin
+only, enforced in the database. Neither is needed for the feature to work; they
+are for the afternoon somebody's laptop dies mid-edit and two minutes is too
+long to wait.