@bygghammar/cms-platform 0.90.0-m7.1 → 0.90.0-m7.11

package/CHANGELOG.md

@@ -8,6 +8,267 @@ 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.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
+  tagged and never published: two defects in the release workflow stopped them
+  after every gate had passed. The form-identity work they were meant to carry
+  is unchanged and ships here.
+- The release workflow gets both corrections, proven in lightweight-popup:
+  the redundant post-checkout `git fetch` is gone (checkout already brings
+  every branch, and its credentials are removed on the way out), and
+  `npm pack`'s destination is created before it is packed into, with the same
+  directory carried to the tarball verification rather than spelled twice.
+- `ops/verify-release-tag.mjs` checks `refs/remotes/origin/main` is present
+  before asking `merge-base` about it, so a checkout that fetched too little no
+  longer reports itself as a tag on an unmerged branch.
+
+## 0.90.0-m7.6
+
+- A form submitted from inside a popup now says so. `FormRenderer` and
+  `ManagedForm` take an opaque `context` that is merged into the submission,
+  and the popup module fills it with `{ popupKey }` — the form system keeps
+  knowing nothing about the features that use it. Without this the request was
+  indistinguishable from the same form filled on an ordinary page, so the
+  server stored an ordinary entry and every delivery configured on the popup
+  silently did nothing.
+- `HostSubmitFormInput` gains `popupKey?: string`, the only popup-shaped value
+  the browser sends. Destination, endpoint, signing secret and which fields may
+  leave are all read on the server from the popup's stored configuration.
+- Drafts and the builder preview carry no context, so a part-filled form and an
+  editor checking a layout cannot fire a campaign's webhook.
+- Requires `@bygghammar/lightweight-popup@>=0.2.0-m7.6`, which is where the
+  identity comes from.
+
+## 0.90.0-m7.5
+
+- `BackofficeHost.pages.fns.listPages` is declared. It was what
+  `cmsPageDirectory` had always looked for, read through an index cast because
+  the contract did not name it — so a site could not register it without a type
+  error, and every site that had not silently got a picker with nothing in it.
+  The top-level lookup stays for anyone who registered it there anyway.
+
+- Requires `@bygghammar/lightweight-popup@>=0.2.0-m7.5`. In `m7.4` an advanced
+  path rule could not be typed: the row was reclassified after the first
+  keystroke and disappeared. No change here beyond the floor — a site pairing
+  this with `m7.4` would get a picker whose rules field does not work.
+
+## 0.90.0-m7.4
+
+- `cmsPageDirectory` takes the site's routing engine and asks it for each
+  page's public path, instead of assuming the page key is the path. The home
+  page is why: its key is `home` and its address is `/`, so the popup page
+  picker would have offered an address that matches nothing.
+- The Popups screen supplies that resolver from the `usePageUrl` hook the
+  backoffice already registers — no new host field, no second pages query. The
+  hook is called from its own component so it stays unconditional while the
+  page group remains optional.
+- Requires `@bygghammar/lightweight-popup@>=0.2.0-m7.4`, which is where the
+  page picker itself lives.
+
+## 0.90.0-m7.3
+
+- Popup exclusions are derived from the configured `backofficePath`, so a site
+  that mounts its office at `/admin` or `/cms/backoffice` is covered without
+  naming it twice. Both the tree and its landing page are excluded: `/admin/**`
+  does not match `/admin`.
+- `registerPopupPublicHost` accepts `excludedPaths` for a site's own private
+  routes — a checkout, a members' area. The CMS adds to that list and never
+  replaces it, and drops duplicates rather than repeating a path.
+- Requires `@bygghammar/lightweight-popup@>=0.2.0-m7.3`, whose defaults no
+  longer name anyone's backoffice.
+
+## 0.90.0-m7.2
+
+- `backofficePaths` gains `popups` and `popupDestinations`, and both popup
+  mount points supply them to the package's navigation. The destinations screen
+  was reachable only by typing its address.
+- Requires `@bygghammar/lightweight-popup@>=0.2.0-m7.2`, which is where the
+  navigation itself lives.
+
 ## 0.90.0-m7.1
 
 First version published to npm rather than vendored as a tarball. Same code as

package/README.md

@@ -25,6 +25,14 @@ 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.
+
 ## Compatibility policy
 
 - `CHANGELOG.md` records every release; read it before upgrading.
@@ -119,8 +127,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.