@bygghammar/cms-platform 0.93.0 → 0.95.0

package/CHANGELOG.md

@@ -8,6 +8,147 @@ 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.95.0
+
+- **Pages can be link-only, and unpublished from the page itself.** Listing is
+  a second property beside publication, and neither changes the other:
+  - **Make link-only / Show on website** (`setPageListingCore`). A link-only
+    page stays online at its address but is left out of menus, the footer and
+    the sitemap, and gets `noindex`. No publication, version, schedule or
+    status is written, so "Show on website" cannot publish an offline page,
+    and saving, publishing and scheduled replacements keep a page link-only.
+    Link-only is not access control.
+  - **Unpublish** (the existing `cms_set_page_status`) is also offered in the
+    builder header. Both actions are in the page builder and the pages list,
+    and ask for confirmation with the consequences spelled out in full.
+  - **Protected pages.** A host passes `protectedPageKeys` in the page deps
+    (Voyara: the start page and the contact page). The server refuses to
+    unpublish, end-date, trash or unlist them. This is an application
+    safeguard; direct database access is not blocked by it.
+  - Offline states read `Offline`, `Scheduled to go offline` and
+    `Offline after expiry` (previously "Hidden…"), so they cannot be confused
+    with link-only.
+  - A copy of a link-only page starts link-only. A same-key retry completes a
+    copy whose listing write failed, with the original decision, and never
+    changes a finished copy: the decision is applied only if the database
+    recorded it before the copy existed. Booking exceptions are never copied.
+- **A site-wide booking switch, with exception pages.** One switch
+  (`setBookingEnabledCore`, Booking card: `./backoffice/BookingSettingsCard`)
+  hides every link to a host starting with `booking` (`isBookingHref`) in page
+  content, the menu, the footer and popups, plus a header CTA the host marks
+  `booking: true`. Pages marked as exceptions keep the booking links in their
+  own content. Stored content is never changed: hosts remove booking from data
+  before it leaves the server (`stripBookingDeep`, `withoutBookingPopups`),
+  and the page renderer can apply the same removal to whatever the browser
+  cache holds.
+- **One public policy for publication, listing and booking**
+  (`loadPublicPolicyCore`, `./cms/page-visibility`). It is read in one
+  snapshot and cached with the published-page cache. A read begun before an
+  invalidation can no longer refill the cache with the old answer. A failed
+  read throws and is not cached, and hosts fail closed.
+  - Hosts send the chrome only the hidden addresses the menu and footer link
+    to (`routeAliasMap` from `./site/route-aliases`; `restrictToLinks` and
+    `savedLinkHrefs` from `./navigation/visibility`) and provide them through
+    `LinkVisibilityProvider` (`./site/link-visibility`). The saved menu is
+    never changed.
+  - The public page route takes a per-page `pagePolicy`: an offline page
+    answers 404 even when the browser has it cached, a cached "not found" is
+    re-read once the page is live, and a non-indexable page gets `noindex`.
+    `PageRenderer` accepts an optional `transform` and `variant`, so the
+    current policy decides over a warm page cache.
+- **Popups follow the booking switch without losing anything else.** The
+  popup module is no longer remounted when the policy changes. While booking
+  is hidden, booking popups are kept paused, with their booking links and
+  actions taken out, so an open one stays readable and closes normally. The
+  restriction applies at once from what is already loaded, without waiting for
+  a refresh, and a slow, failed or late refresh cannot bring booking back.
+  An open newsletter form keeps its field, text and focus, its trigger timers,
+  counts and analytics.
+- **Storage: no migration.** One `site_settings` row per decision
+  (`page.listing.<uuid>`, `booking`, `booking.exception.<uuid>`, and a
+  short-lived `duplicate.intent.<key>` during a duplication). Every write is a
+  compare-and-swap on `updated_at` (`VisibilityConflictError`). None of these
+  keys can be reached by the generic settings save or reset.
+- **New exports:**
+  - `./cms/page-visibility`;
+  - `./cms/booking-links`;
+  - `./server/page-visibility-core`;
+  - `./navigation/visibility`;
+  - `./site/link-visibility`;
+  - `./site/route-aliases`;
+  - `./backoffice/BookingSettingsCard`.
+
+  The new host wiring is optional (`pages.fns.setPageListing`, `booking.fns`,
+  `useLinkVisibility`); without it the new actions and the Booking card are
+  not shown. See `docs/PAGES.md`.
+
+## 0.94.0
+
+- **The version screen shows what is actually deployed and installed.**
+  `/admin/version`, now "Version & modules", no longer labels the site's
+  `package.json` version as the "CMS build". It shows:
+  - the release identity from the runtime `APP_VERSION` (falling back to
+    `VITE_PUBLIC_APP_VERSION`, the values the health check reports), short,
+    in full and with a copy control, or "Unknown";
+  - the build time, labelled as such, and a deployment time only when the
+    host supplies real evidence; otherwise "Not recorded";
+  - the installed CMS package and module packages: installed and declared
+    versions, publication dates, the newest version in their channel and an
+    advisory status;
+  - every module from the module table, with its enabled status read from
+    the same saved settings as Site settings. A loading or failed settings
+    read is shown as such, never as the compiled defaults;
+  - recent CMS releases, and the packaged schema figures labelled as package
+    facts rather than a check of the live database.
+
+  The screen never changes settings.
+- **Update policy.** Versions are compared by semver precedence, not as
+  strings or by publication date.
+  - A release install follows stable releases.
+  - A prerelease install follows its prerelease line (`0.2.0-m7`) and is
+    reported as "Prerelease installed", not "Up to date".
+  - Unknown, malformed, unpublished or ahead-of-registry versions, and any
+    case without a registry answer, are never "Up to date".
+- **Registry reads are bounded and server-side.** `admin/registry-metadata`
+  looks up only the allowlisted first-party packages (the CMS package plus
+  packages named by modules) in the public npm registry:
+  - anonymous, refusing redirects, with a 5 s timeout and an 8 MiB cap;
+  - a 15-minute cache, and at most one attempt per package per minute,
+    manual "Check again" included;
+  - shared in-flight requests.
+
+  `fetchPlatformReleases` now goes through the same client.
+- **Failed checks are never shown as current.**
+  - When a later registry attempt fails, the last good answer stays on
+    screen marked "Not re-verified", with its success and failure times.
+  - A package that has never been checked successfully says so.
+  - A failed "Check again" or re-read shows an alert and keeps the last
+    answer, marked as not re-verified, without the raw error.
+  - The next successful answer clears these notices.
+- **New contract pieces (additive):**
+  - in `admin/version-core`: `buildVersionReport`, `readReleaseIdentity`,
+    `readEnvironment`, `readInstalledPackages`, `releasesFromReport`,
+    `FIRST_PARTY_PACKAGES` and `platformRegistryClient`;
+  - the `./admin/version-report` export: report types,
+    `evaluatePackageUpdate` and `summarizeUpdates`;
+  - an optional `package` field on `CmsModuleDefinition` (Popups declares
+    `@bygghammar/lightweight-popup`);
+  - `status` from `useResolvedSiteConfig()`;
+  - optional `report`, `modules`, `latestCheckFailed` and `onRefresh` props
+    on `VersionView`.
+
+  A host whose `getSystemVersion` still returns only `{ build, releases }`
+  keeps rendering, with the release shown as unknown and no update check.
+- **Host side:**
+  - protect `getSystemVersion` with the site's auth middleware and
+    `assertStaff`;
+  - accept `{ refresh?: boolean }` and pass it to `buildVersionReport`;
+  - inject the installed package list as the `packages` build constant
+    (`[{ name, installed, declared, requiredByCms }]`, read from
+    `node_modules` at build time).
+
+  Voyara's adoption does all three.
+
 ## 0.93.0
 
 - **Breaking for callers of `responsiveImage`, and for transparent images in

package/docs/PAGES.md

@@ -92,11 +92,15 @@ show the state the rule produces — `publicationStateAt` over the page's own
 
 | State | Badge | Means |
 | --- | --- | --- |
-| `draft` | Hidden | Nothing open, nothing scheduled |
-| `scheduled` | Scheduled to publish | Hidden now; a window opens later |
+| `draft` | Offline | Nothing open, nothing scheduled |
+| `scheduled` | Scheduled to publish | Offline 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 |
+| `ending` | Scheduled to go offline | Public, with an end date already set |
+| `expired` | Offline after expiry | Was public; the window has closed |
+
+(These read "Hidden", "Scheduled to hide" and "Hidden after expiry" until
+listing was added: a link-only page is *online* but unlisted, and the two must
+not share a word. See [Listing, link-only pages and booking](#listing-link-only-pages-and-booking).)
 
 `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
@@ -508,3 +512,67 @@ A host that has not registered them keeps working — the Pages list hides the t
 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.
+
+## Listing, link-only pages and booking
+
+Listing is a second property beside publication, and the two never touch:
+
+| Publication | Listing | Shown as | A visitor gets |
+| --- | --- | --- | --- |
+| live | listed | `Published` | The page; it is in menus, footer and sitemap |
+| live | link-only | `Published` + `Link only` | The page by its address only; left out of menus, footer and sitemap; `noindex` |
+| not live | either | `Offline` (+ `Link only once published`) | 404 |
+
+- **Make link-only / Show on website** change listing only (`setPageListingCore`).
+  No publication, version, schedule or `pages.status` is written, so "Show on
+  website" cannot publish an offline page, and saving, publishing and scheduled
+  replacements keep a page link-only. Link-only is not access control: the
+  address can be shared or found, and `noindex` asks crawlers, it does not
+  remove existing results.
+- **Unpublish** is the existing `cms_set_page_status(draft)` with its
+  schedule-aware warnings, now also offered in the builder header.
+- **Protected pages.** A host passes `protectedPageKeys` in the page deps (Voyara:
+  the start page and the contact page). The cores refuse to unpublish, end-date,
+  trash or unlist them. An application safeguard: direct database access is not
+  blocked by it.
+- **Booking.** One switch hides every link whose address is `https:` (or
+  protocol-relative) with a host starting `booking` (`isBookingHref`), plus the
+  header CTA when the host marks it `booking: true`. Exception pages keep the
+  booking links in their own content. Removal (`stripBookingDeep`,
+  `withoutBookingPopups`) is for the host to apply to data before it leaves the
+  server; stored content is never changed.
+
+### Storage
+
+No migration: one `site_settings` row per decision, keyed by page id —
+`page.listing.<uuid>`, `booking`, `booking.exception.<uuid>`. Every write is a
+compare-and-swap on `updated_at` (`VisibilityConflictError` when someone else
+changed the row first). None is an `OVERRIDABLE_SETTING_KEYS` key, so the generic
+settings save and reset cannot reach them.
+
+### The public policy
+
+`loadPublicPolicyCore` reads publication, listing, booking and exceptions for
+every page in one snapshot, cached with the published-page cache (cleared on
+every page and visibility write, capped at the next publication boundary). A
+failed read throws and is not cached; hosts fail closed (`known: false`: booking
+hidden, nothing indexable, nothing reported offline).
+
+Hosts turn the snapshot into what the chrome needs with `routeAliasMap`,
+`restrictToLinks` and `savedLinkHrefs` — only the hidden addresses the menu and
+footer actually link to are sent to the browser — and provide it through
+`LinkVisibilityProvider`. The header and footer leave those links out; the
+saved menu is never changed, and the navigation editor says why an item is not
+shown. The public page route takes a per-page `pagePolicy` query and adds
+`noindex` for a page that is not indexable.
+
+### Host wiring
+
+```ts
+pages: { fns: { setPageStatus?, setPageListing?, ... } }
+booking?: { fns: { getBookingSettings, setBookingEnabled, setBookingException } }
+useLinkVisibility?: () => LinkVisibilityPolicy | undefined
+```
+
+All optional: without them the actions, the Booking card and the editor's
+explanation are simply not shown.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bygghammar/cms-platform",
-  "version": "0.93.0",
+  "version": "0.95.0",
   "description": "Shared CMS platform: blocks, block types, i18n core, UI primitives and design-token contract used by every Bygghammar/Voyara site.",
   "type": "module",
   "sideEffects": [
@@ -49,6 +49,7 @@
     "./trips": "./src/trips/index.ts",
     "./trips/TripSectionEditor": "./src/trips/TripSectionEditor.tsx",
     "./navigation": "./src/navigation/index.ts",
+    "./navigation/visibility": "./src/navigation/visibility.ts",
     "./forms/FormRenderer": "./src/forms/FormRenderer.tsx",
     "./forms/success": "./src/forms/success-listeners.ts",
     "./forms/submission-result": "./src/forms/submission-result.ts",
@@ -124,6 +125,7 @@
     "./config/site-config": "./src/config/site-config.ts",
     "./server/site-settings-core": "./src/server/site-settings-core.ts",
     "./backoffice/SiteSettingsView": "./src/backoffice/SiteSettingsView.tsx",
+    "./backoffice/BookingSettingsCard": "./src/backoffice/BookingSettingsCard.tsx",
     "./backoffice/SitemapView": "./src/backoffice/SitemapView.tsx",
     "./backoffice/UsersView": "./src/backoffice/UsersView.tsx",
     "./backoffice/RolesView": "./src/backoffice/RolesView.tsx",
@@ -154,6 +156,7 @@
     "./server/media-library-core": "./src/server/media-library-core.ts",
     "./server/admin-core": "./src/server/admin-core.ts",
     "./server/pages-core": "./src/server/pages-core.ts",
+    "./server/page-visibility-core": "./src/server/page-visibility-core.ts",
     "./server/edit-locks-core": "./src/server/edit-locks-core.ts",
     "./server/edit-lock-adapter": "./src/server/edit-lock-adapter.ts",
     "./server/edit-lock-supabase-adapter": "./src/server/edit-lock-supabase-adapter.ts",
@@ -186,6 +189,7 @@
     "./site/public-origin": "./src/site/public-origin.ts",
     "./site/font-bundle": "./src/site/font-bundle.ts",
     "./admin/version-core": "./src/admin/version-core.ts",
+    "./admin/version-report": "./src/admin/version-report.ts",
     "./config/package-owned-modules": "./src/config/package-owned-modules.ts",
     "./modules": "./src/modules/index.ts",
     "./popups/host": "./src/popups/host.ts",
@@ -204,6 +208,8 @@
     "./media/use-media-upload": "./src/media/use-media-upload.ts",
     "./cms/page-draft-store": "./src/cms/page-draft-store.ts",
     "./cms/page-publication": "./src/cms/page-publication.ts",
+    "./cms/page-visibility": "./src/cms/page-visibility.ts",
+    "./cms/booking-links": "./src/cms/booking-links.ts",
     "./site/routes": "./src/site/routes.ts",
     "./site/PageRenderer": "./src/site/PageRenderer.tsx",
     "./server/env": "./src/server/env.ts",
@@ -231,6 +237,8 @@
     "./site/host": "./src/site/host.ts",
     "./site/locale-domains": "./src/site/locale-domains.ts",
     "./site/route-index": "./src/site/route-index.ts",
+    "./site/route-aliases": "./src/site/route-aliases.ts",
+    "./site/link-visibility": "./src/site/link-visibility.tsx",
     "./site/SiteHeader": "./src/site/SiteHeader.tsx",
     "./site/SiteFooter": "./src/site/SiteFooter.tsx",
     "./server/schemas": "./src/server/schemas.ts",

package/src/admin/describe-log.ts

@@ -34,6 +34,9 @@ export const ACTION_LABELS: Record<string, string> = {
   "page.delete": "Deleted page",
   "page.publish": "Published page",
   "page.unpublish": "Unpublished page",
+  "page.listing": "Changed whether a page is listed",
+  "booking.settings": "Switched booking on or off",
+  "booking.exception": "Changed which pages keep booking links",
   "page.version.create": "Saved page version",
   "page.version.restore": "Restored page version",
   "template.create": "Created block template",

package/src/admin/module-inventory.ts

@@ -0,0 +1,67 @@
+/**
+ * The version screen's module list, derived from the module table.
+ *
+ * Every module is listed, enabled or not: switching a module off in Site
+ * settings hides it, it does not remove its code from the build. Whether it is
+ * on comes from the same saved settings the Settings screen and the sidebar
+ * read. Until that read has succeeded, the status is "checking" or
+ * "unavailable" — never the compiled default presented as the live answer.
+ */
+import { CMS_MODULE_LIST, type CmsModuleKey } from "../config/modules";
+import type { PackageReport } from "./version-report";
+
+/** The state of the saved-settings read the enabled flags come from. */
+export type ModuleSettingsRead =
+  | { readonly state: "loading" }
+  | { readonly state: "error" }
+  | {
+      readonly state: "ready";
+      readonly features: Readonly<Partial<Record<CmsModuleKey, boolean>>>;
+      /** True when a later re-read failed and these values are from an earlier one. */
+      readonly stale?: boolean;
+    };
+
+export type ModuleEnabledState = "enabled" | "disabled" | "checking" | "unavailable";
+
+export type ModuleInventoryRow = {
+  readonly key: CmsModuleKey;
+  readonly label: string;
+  readonly description: string | null;
+  readonly enabled: ModuleEnabledState;
+  /** True when `enabled` comes from an earlier successful read. */
+  readonly enabledStale: boolean;
+  /** Installed CMS package version the module ships inside, when known. */
+  readonly cmsVersion: string | null;
+  /** The separately published package the module is built on, if any. */
+  readonly packageName: string | null;
+  /** That package's report, when the host supplied one. */
+  readonly package: PackageReport | null;
+};
+
+/** One row per module, in module-table order. */
+export function moduleInventory(
+  settings: ModuleSettingsRead,
+  packages: readonly PackageReport[] | null | undefined,
+  cmsVersion: string | null | undefined,
+): ModuleInventoryRow[] {
+  return CMS_MODULE_LIST.map((m) => {
+    let enabled: ModuleEnabledState;
+    if (settings.state === "loading") enabled = "checking";
+    else if (settings.state === "error") enabled = "unavailable";
+    else {
+      const value = settings.features[m.key];
+      enabled = value === true ? "enabled" : value === false ? "disabled" : "unavailable";
+    }
+    const packageName = m.package ?? null;
+    return {
+      key: m.key,
+      label: m.label,
+      description: m.description ?? null,
+      enabled,
+      enabledStale: settings.state === "ready" && settings.stale === true,
+      cmsVersion: cmsVersion ?? null,
+      packageName,
+      package: packageName ? (packages?.find((p) => p.name === packageName) ?? null) : null,
+    };
+  });
+}

package/src/admin/registry-metadata.ts

@@ -0,0 +1,256 @@
+/**
+ * Bounded, cached reads of public npm registry metadata — server side only.
+ *
+ * The version screen compares installed first-party packages with what has
+ * been published. That comparison must never be able to hurt the page or the
+ * server, so every read here is:
+ *
+ * - **allowlisted**: only package names the caller fixed at construction are
+ *   looked up; the URL is built here from the fixed registry origin, never from
+ *   request input. Anything else answers `not-allowed` without a request.
+ * - **anonymous**: no credentials, tokens or cookies are sent, and redirects are
+ *   refused so the request cannot be bounced elsewhere.
+ * - **bounded**: a timeout covers the whole response, and bodies over a size
+ *   cap are abandoned.
+ * - **cached**: a successful answer is reused for `freshForMs`; after any
+ *   attempt, successful or not, the registry is not asked again for that
+ *   package for `retryAfterMs`, even when a manual refresh is requested.
+ *   Concurrent callers share one request.
+ * - **failure-tolerant**: a failed read keeps serving the last good answer as
+ *   `stale` (cached, not re-verified) with the failure's fixed reason code —
+ *   never the registry's own text — until a later attempt succeeds.
+ */
+import { parseSemver } from "./semver";
+import type {
+  RegistryCheck,
+  RegistryError,
+  RegistryMetadata,
+  RegistryVersion,
+} from "./version-report";
+
+/** The only registry this module talks to. */
+export const NPM_REGISTRY_ORIGIN = "https://registry.npmjs.org";
+
+/** Scoped npm package names only (`@scope/name`), lower case. */
+const PACKAGE_NAME = /^@[a-z0-9][a-z0-9._-]{0,63}\/[a-z0-9][a-z0-9._-]{0,127}$/;
+
+export type RegistryLookup = {
+  readonly metadata: RegistryMetadata | null;
+  readonly check: RegistryCheck;
+};
+
+export type RegistryClientOptions = {
+  /** Exact package names that may be looked up. */
+  readonly allowlist: readonly string[];
+  /** Injected for tests; defaults to the global `fetch` at call time. */
+  readonly fetch?: (input: string, init: RequestInit) => Promise<Response>;
+  /** Injected for tests; milliseconds since the epoch. */
+  readonly now?: () => number;
+  /** How long a successful answer counts as fresh. Default 15 minutes. */
+  readonly freshForMs?: number;
+  /** Minimum time between two attempts for one package. Default 60 seconds. */
+  readonly retryAfterMs?: number;
+  /** Timeout for one request, body included. Default 5 seconds. */
+  readonly timeoutMs?: number;
+  /** Largest response body accepted. Default 8 MiB. */
+  readonly maxBytes?: number;
+};
+
+export type RegistryClient = {
+  lookup(name: string, options?: { refresh?: boolean }): Promise<RegistryLookup>;
+  /** When the next attempt for `name` may reach the registry (epoch ms), or null if now. */
+  nextAttemptAt(name: string): number | null;
+};
+
+/** The registry URL for a scoped package (`@scope%2Fname`). */
+export function registryUrl(name: string): string {
+  return `${NPM_REGISTRY_ORIGIN}/${name.replace("/", "%2F")}`;
+}
+
+function iso(ms: number | null | undefined): string | null {
+  return typeof ms === "number" && Number.isFinite(ms) ? new Date(ms).toISOString() : null;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Reduce a registry document to the fields the screen uses, or `null` when it
+ * does not have the expected shape. Versions that are not valid semver are
+ * dropped; a document with no usable version at all is malformed.
+ */
+export function parseRegistryDocument(doc: unknown): RegistryMetadata | null {
+  if (!isRecord(doc) || !isRecord(doc["versions"])) return null;
+  const time = isRecord(doc["time"]) ? doc["time"] : {};
+  const rawTags = isRecord(doc["dist-tags"]) ? doc["dist-tags"] : {};
+
+  const versions: Record<string, RegistryVersion> = {};
+  for (const [key, entry] of Object.entries(doc["versions"])) {
+    const sv = parseSemver(key);
+    if (!sv) continue;
+    const stamp = time[key];
+    const ms = typeof stamp === "string" ? Date.parse(stamp) : Number.NaN;
+    const deprecated = isRecord(entry) && typeof entry["deprecated"] === "string";
+    versions[sv.version] = {
+      publishedAt: Number.isFinite(ms) ? new Date(ms).toISOString() : null,
+      deprecated: deprecated && (entry["deprecated"] as string).length > 0,
+    };
+  }
+  if (Object.keys(versions).length === 0) return null;
+
+  const distTags: Record<string, string> = {};
+  for (const [tag, value] of Object.entries(rawTags)) {
+    const sv = parseSemver(value);
+    if (sv && /^[A-Za-z0-9._-]{1,64}$/.test(tag)) distTags[tag] = sv.version;
+  }
+  return { distTags, versions };
+}
+
+async function readBounded(res: Response, maxBytes: number): Promise<string | null> {
+  const declared = Number(res.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > maxBytes) {
+    await res.body?.cancel().catch(() => {});
+    return null;
+  }
+  if (!res.body) {
+    const text = await res.text();
+    return new TextEncoder().encode(text).byteLength > maxBytes ? null : text;
+  }
+  const reader = res.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > maxBytes) {
+      await reader.cancel().catch(() => {});
+      return null;
+    }
+    chunks.push(value);
+  }
+  const all = new Uint8Array(total);
+  let offset = 0;
+  for (const c of chunks) {
+    all.set(c, offset);
+    offset += c.byteLength;
+  }
+  return new TextDecoder().decode(all);
+}
+
+/** Create a registry client. One per process is the intended use. */
+export function createRegistryClient(options: RegistryClientOptions): RegistryClient {
+  const allowed = new Set(options.allowlist.filter((n) => PACKAGE_NAME.test(n)));
+  const now = options.now ?? (() => Date.now());
+  const freshForMs = options.freshForMs ?? 15 * 60_000;
+  const retryAfterMs = options.retryAfterMs ?? 60_000;
+  const timeoutMs = options.timeoutMs ?? 5_000;
+  const maxBytes = options.maxBytes ?? 8 * 1024 * 1024;
+
+  const good = new Map<string, { metadata: RegistryMetadata; at: number }>();
+  const attempts = new Map<string, { at: number; error: RegistryError | null }>();
+  const inflight = new Map<string, Promise<void>>();
+
+  async function attempt(name: string): Promise<void> {
+    const startedAt = now();
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let error: RegistryError | null = null;
+    try {
+      const doFetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+      const res = await doFetch(registryUrl(name), {
+        method: "GET",
+        headers: { accept: "application/json" },
+        redirect: "error",
+        credentials: "omit",
+        signal: controller.signal,
+      });
+      if (res.status === 404) {
+        error = "not-found";
+        await res.body?.cancel().catch(() => {});
+      } else if (!res.ok) {
+        error = "http";
+        await res.body?.cancel().catch(() => {});
+      } else {
+        const text = await readBounded(res, maxBytes);
+        if (text === null) {
+          error = "too-large";
+        } else {
+          let doc: unknown;
+          try {
+            doc = JSON.parse(text);
+          } catch {
+            doc = undefined;
+          }
+          const metadata = parseRegistryDocument(doc);
+          if (metadata) good.set(name, { metadata, at: startedAt });
+          else error = "malformed";
+        }
+      }
+    } catch {
+      error = controller.signal.aborted ? "timeout" : "network";
+    } finally {
+      clearTimeout(timer);
+    }
+    attempts.set(name, { at: startedAt, error });
+  }
+
+  function snapshot(name: string): RegistryLookup {
+    const hit = good.get(name);
+    const last = attempts.get(name);
+    // Fresh only when the most recent attempt is the successful one and it is
+    // within the lifetime. A newer failed attempt leaves the last good answer
+    // in place, but as cached and unverified, never as current.
+    const latestFailed = last !== undefined && last.error !== null;
+    const state = !hit
+      ? "unavailable"
+      : latestFailed || now() - hit.at >= freshForMs
+        ? "stale"
+        : "fresh";
+    return {
+      metadata: hit?.metadata ?? null,
+      check: {
+        state,
+        lastSuccessAt: iso(hit?.at),
+        lastAttemptAt: iso(last?.at),
+        error: last?.error ?? null,
+      },
+    };
+  }
+
+  function nextAttemptAt(name: string): number | null {
+    const last = attempts.get(name);
+    if (!last) return null;
+    const next = last.at + retryAfterMs;
+    return next > now() ? next : null;
+  }
+
+  return {
+    nextAttemptAt,
+    async lookup(name, { refresh = false } = {}) {
+      if (!allowed.has(name)) {
+        return {
+          metadata: null,
+          check: { state: "unavailable", lastSuccessAt: null, lastAttemptAt: null, error: "not-allowed" },
+        };
+      }
+      const hit = good.get(name);
+      const fresh = hit !== undefined && now() - hit.at < freshForMs;
+      const throttled = nextAttemptAt(name) !== null;
+      if (!throttled && (refresh || !fresh)) {
+        let pending = inflight.get(name);
+        if (!pending) {
+          pending = attempt(name).finally(() => inflight.delete(name));
+          inflight.set(name, pending);
+        }
+        await pending;
+      } else {
+        // Someone else may be mid-request; share its answer rather than a stale one.
+        const pending = inflight.get(name);
+        if (pending) await pending;
+      }
+      return snapshot(name);
+    },
+  };
+}