create-shapio 0.5.0 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-shapio",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Scaffold a new Shapio project (npx create-shapio my-cms) or a site starter (--site astro|next|sveltekit)",
   "license": "Apache-2.0",
   "homepage": "https://shapio.dev",

package/templates/astro/.env.example

@@ -10,3 +10,9 @@ SHAPIO_DELIVERY_TOKEN=
 # PUBLIC_SHAPIO_URL=https://cms.example.com
 # Optional: this site's public origin; pages then carry a canonical URL and og:url.
 # SITE_URL=https://www.example.com
+# Optional, development only: drafts mode. Every read shows saved drafts instead of published content, fresh
+# on every request, with a "Drafts" badge on each page. Needs a delivery token whose role grants Read drafts:
+# SHAPIO_DEV_DELIVERY_TOKEN (`npm run seed` writes one), else SHAPIO_DELIVERY_TOKEN. Never put that token or
+# this flag in a production environment.
+# SHAPIO_DRAFTS=true
+# SHAPIO_DEV_DELIVERY_TOKEN=

package/templates/astro/README.md

@@ -19,6 +19,15 @@ npm run smoke:http  # checks the served pages over HTTP (in another terminal, wh
 `SHAPIO_DELIVERY_TOKEN` to `.env`. Other settings (`SHAPIO_SNAPSHOT`, `SHAPIO_SITE`, `PUBLIC_SHAPIO_URL`) are
 in `.env.example`. Astro's telemetry is turned off in the npm scripts.
 
+Drafts mode, for your development server: set `SHAPIO_DRAFTS=true` in `.env` and `npm run dev` shows saved
+drafts instead of published content, fresh on every reload, with a **Drafts** badge on every page. Save in
+Shapio, reload, and the change is there; publishing still rebuilds the live site. It reads with
+`SHAPIO_DEV_DELIVERY_TOKEN`, the seed's `<site> dev` token, whose delivery role grants Read drafts (a token
+without it fails with `DRAFTS_FORBIDDEN`). Never put that token or the flag in a production environment.
+`npm run smoke:drafts` checks a running drafts-mode dev server
+(http://localhost:4321; needs `SHAPIO_ADMIN_EMAIL`/`PASSWORD` to save a test change, which it puts back). Guide:
+[drafts mode](https://github.com/mybrokengnome/shapio/blob/main/documentation/starters.md#drafts-mode).
+
 Preview: the seed creates a deployment connection named **Preview** that opens drafts at
 `http://localhost:4321/preview/` (set `SITE_URL` when seeding for another address). Add that origin to Shapio's
 `CORS_ORIGINS`. In Shapio's preview pane, clicking the title, body or cover focuses that field and saves

package/templates/astro/package.json

@@ -13,19 +13,22 @@
     "preview": "ASTRO_TELEMETRY_DISABLED=1 astro preview",
     "seed": "node --env-file-if-exists=.env --import tsx scripts/seed.ts --site-url http://localhost:4321",
     "smoke": "node --env-file-if-exists=.env --import tsx scripts/smoke.ts",
+    "smoke:drafts": "node --env-file-if-exists=.env --import tsx scripts/smokeDrafts.ts --url http://localhost:4321",
     "smoke:http": "node --import tsx scripts/smokeHttp.ts --url http://localhost:4321",
     "report-status": "node --env-file-if-exists=.env --import tsx scripts/reportStatus.ts",
     "build:incremental": "node --env-file-if-exists=.env --import tsx scripts/incrementalBuild.ts",
-    "typecheck": "tsc -p tsconfig.json"
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run"
   },
   "dependencies": {
-    "@shapio/client": "^0.5.0",
-    "@shapio/visual": "^0.5.0",
+    "@shapio/client": "^0.5.1",
+    "@shapio/visual": "^0.5.1",
     "astro": "7.3.5"
   },
   "devDependencies": {
     "@types/node": "24.19.1",
     "tsx": "4.23.15",
-    "typescript": "6.0.3"
+    "typescript": "6.0.3",
+    "vitest": "5.0.3"
   }
 }

package/templates/astro/scripts/seed.ts

@@ -40,13 +40,16 @@ import { createPng } from './lib/png.js';
  * 5. with `--revalidate-path` (the Next.js starter's /api/revalidate), a webhook named "Site revalidation" that
  *    sends publish, unpublish, delete, change set and schema events to SITE_URL + that path; its signing secret
  *    (rotated on every run, as Shapio shows it only once) is written to .env as SHAPIO_WEBHOOK_SECRET;
- * 6. a delivery role and token for the build, written with SHAPIO_URL to .env in the current directory.
+ * 6. a delivery role and token for the build, written with SHAPIO_URL to .env in the current directory;
+ * 7. a second delivery role and token for development servers, "<site> dev", that may also read drafts (drafts
+ *    mode: SHAPIO_DRAFTS=true), written to .env as SHAPIO_DEV_DELIVERY_TOKEN. Never put it in production.
  */
 const SCHEMA_DIR = resolve(import.meta.dirname, '..', 'shapio');
 const SCHEMA_KINDS = ['models', 'components'] as const;
 const SITE_MODELS = ['page', 'article', 'author', 'siteSettings'];
 const DELIVERY_ROLE_KEY = 'starter-delivery';
 const DELIVERY_TOKEN_NAME = 'starter build';
+const DEV_ROLE_KEY = 'starter-dev';
 const PREVIEW_CONNECTION_NAME = 'Preview';
 /** Where Shapio opens a draft: the starter's /preview/ page, the token in the fragment (never sent to a server). */
 const PREVIEW_PATH = '/preview/?model={modelKey}&id={entryId}&locale={locale}#token={token}';
@@ -308,35 +311,71 @@ const upsertEntry = async (client: ShapioClient, spec: EntrySpec) => {
   log(`${spec.publish ? 'Published' : 'Saved draft'} ${spec.model} ${spec.slug} (en, fr)`);
 };
 
-/** A delivery role that reads the site's models, and a fresh token bound to it (older ones are revoked). */
-const createDeliveryToken = async (client: ShapioClient) => {
+type DeliveryRoleSpec = {
+  key: string;
+  name: string;
+  description: string;
+  tokenName: string;
+  drafts: boolean;
+};
+
+/**
+ * A delivery role that reads the site's models (and, for development servers, their drafts), and a fresh token
+ * bound to it (older ones of the same name are revoked).
+ */
+const createDeliveryToken = async (client: ShapioClient, spec: DeliveryRoleSpec) => {
   const summary = await client.admin.schema.summary();
   const modelIds = summary.definitions
     .filter((definition) => SITE_MODELS.includes(definition.apiKey))
     .map((definition) => definition.id);
-  const permissions = modelIds.map((modelId) => ({
-    action: 'read' as const,
-    modelId,
-    condition: null,
-    fieldIds: null,
-  }));
+  const grant = { condition: null, fieldIds: null };
+  const permissions = [
+    ...modelIds.map((modelId) => ({ action: 'read' as const, modelId, ...grant })),
+    // Read drafts always covers every model; the role still reads only the models above.
+    ...(spec.drafts ? [{ action: 'readDrafts' as const, modelId: null, ...grant }] : []),
+  ];
   const roles = await client.admin.roles.list();
-  const existing = roles.find((role) => role.key === DELIVERY_ROLE_KEY);
+  const existing = roles.find((role) => role.key === spec.key);
   const role = existing
     ? await client.admin.roles.update(existing.id, { expectedVersion: existing.version, permissions })
     : await client.admin.roles.create({
-        key: DELIVERY_ROLE_KEY,
-        name: 'Starter site (delivery)',
-        description: 'Reads published pages, articles, authors and the site settings for the starter build.',
+        key: spec.key,
+        name: spec.name,
+        description: spec.description,
         kind: 'delivery',
         permissions,
       });
   for (const token of await client.admin.tokens.list()) {
-    if (token.name === DELIVERY_TOKEN_NAME && !token.revokedAt) {
+    if (token.name === spec.tokenName && !token.revokedAt) {
       await client.admin.tokens.revoke(token.id);
     }
   }
-  return (await client.admin.tokens.create({ name: DELIVERY_TOKEN_NAME, roleId: role.id })).token;
+  return (await client.admin.tokens.create({ name: spec.tokenName, roleId: role.id })).token;
+};
+
+const BUILD_ROLE: DeliveryRoleSpec = {
+  key: DELIVERY_ROLE_KEY,
+  name: 'Starter site (delivery)',
+  description: 'Reads published pages, articles, authors and the site settings for the starter build.',
+  tokenName: DELIVERY_TOKEN_NAME,
+  drafts: false,
+};
+
+/** The development token's role: the build role plus Read drafts. Named after the site it reads. */
+const devRole = (siteName: string): DeliveryRoleSpec => ({
+  key: DEV_ROLE_KEY,
+  name: 'Starter site dev (drafts)',
+  description:
+    'Reads the starter models and their drafts, for development servers (drafts mode). Never use its tokens in production.',
+  tokenName: `${siteName} dev`,
+  drafts: true,
+});
+
+/** The name of the site the seed works on: SHAPIO_SITE, else the primary site. */
+const siteNameOf = async (client: ShapioClient, siteKey: string | undefined) => {
+  const sites = await client.admin.sites.list();
+  const site = sites.find((candidate) => (siteKey ? candidate.key === siteKey : candidate.isPrimary));
+  return site?.name ?? siteKey ?? 'site';
 };
 
 /** The "Preview" connection, created once and pointed at this starter's /preview/ page on every run. */
@@ -402,24 +441,30 @@ const tryRevalidateWebhook = async (client: ShapioClient, siteUrl: string, path:
   }
 };
 
-const writeEnv = async (
-  url: string,
-  site: string | undefined,
-  deliveryToken: string,
-  webhookSecret: string | undefined,
-) => {
+type SeededEnv = {
+  url: string;
+  site: string | undefined;
+  deliveryToken: string;
+  devDeliveryToken: string;
+  webhookSecret: string | undefined;
+};
+
+const writeEnv = async ({ url, site, deliveryToken, devDeliveryToken, webhookSecret }: SeededEnv) => {
   const path = resolve('.env');
   const lines = [
-    '# Written by the seed. The delivery token is read-only; keep this file out of git.',
+    '# Written by the seed. The delivery tokens are read-only; keep this file out of git.',
     `SHAPIO_URL=${url}`,
     `SHAPIO_DELIVERY_TOKEN=${deliveryToken}`,
+    '# Development only: drafts mode (SHAPIO_DRAFTS=true) reads with this token, which may read drafts.',
+    '# Never put it in a production environment.',
+    `SHAPIO_DEV_DELIVERY_TOKEN=${devDeliveryToken}`,
     // The site the content was seeded on: the starter reads the same one.
     ...(site ? [`SHAPIO_SITE=${site}`] : []),
     ...(webhookSecret ? [`SHAPIO_WEBHOOK_SECRET=${webhookSecret}`] : []),
   ];
   await writeFile(path, `${lines.join('\n')}\n`, { mode: 0o600 });
   log(
-    `Wrote SHAPIO_URL, ${site ? 'SHAPIO_SITE, ' : ''}SHAPIO_DELIVERY_TOKEN${webhookSecret ? ' and SHAPIO_WEBHOOK_SECRET' : ''} to ${path}`,
+    `Wrote SHAPIO_URL, ${site ? 'SHAPIO_SITE, ' : ''}SHAPIO_DELIVERY_TOKEN, SHAPIO_DEV_DELIVERY_TOKEN${webhookSecret ? ' and SHAPIO_WEBHOOK_SECRET' : ''} to ${path}`,
   );
 };
 
@@ -444,7 +489,15 @@ const main = async () => {
     const webhookSecret = revalidatePath
       ? await tryRevalidateWebhook(admin.client, siteUrl, revalidatePath)
       : undefined;
-    await writeEnv(admin.url, admin.site, await createDeliveryToken(admin.client), webhookSecret);
+    const siteName = await siteNameOf(admin.client, admin.site);
+    await writeEnv({
+      url: admin.url,
+      site: admin.site,
+      deliveryToken: await createDeliveryToken(admin.client, BUILD_ROLE),
+      devDeliveryToken: await createDeliveryToken(admin.client, devRole(siteName)),
+      webhookSecret,
+    });
+    log(`Created the "${siteName} dev" token for drafts mode (SHAPIO_DRAFTS=true); keep it off production.`);
     log('Seeded. Build the site with: npm run build');
   } finally {
     await admin.close();

package/templates/astro/scripts/smokeDrafts.ts

@@ -0,0 +1,109 @@
+import { parseArgs } from 'node:util';
+import { connectAdmin } from './lib/admin.js';
+
+/**
+ * `npm run smoke:drafts`, after `npm run seed` and starting the dev server with SHAPIO_DRAFTS=true (drafts mode,
+ * which reads with the seed's SHAPIO_DEV_DELIVERY_TOKEN): checks that the site shows drafts, that every page
+ * carries the "Drafts" badge, and that a change saved in Shapio (not published) shows on the next reload.
+ * The saved change is put back afterwards. Needs SHAPIO_ADMIN_EMAIL and SHAPIO_ADMIN_PASSWORD (or SHAPIO_TOKEN,
+ * an admin API token) to save the change, as the seed does.
+ *
+ * `--url` is the running dev server's origin (default: SMOKE_URL, then http://localhost:3000).
+ */
+const DRAFT_TITLE = 'Coming soon: our winter projects';
+const ARTICLE = 'modelling-without-a-deploy';
+const BADGE = 'data-shapio-drafts';
+/** How long a saved draft may take to show: the dev server reads fresh, so this only absorbs a slow render. */
+const SHOW_WITHIN_MS = 30_000;
+const POLL_EVERY_MS = 250;
+
+const failures: string[] = [];
+const check = (condition: boolean, message: string) => {
+  process.stdout.write(`${condition ? 'ok  ' : 'FAIL'} ${message}\n`);
+  if (!condition) {
+    failures.push(message);
+  }
+};
+
+const fetchPage = async (origin: string, path: string) => {
+  const response = await fetch(new URL(path, origin));
+  return { status: response.status, html: await response.text() };
+};
+
+/** Reloads `path` until it contains `needle` (a real condition, not a fixed wait); false when it never does. */
+const showsWithin = async (origin: string, path: string, needle: string): Promise<boolean> => {
+  const deadline = Date.now() + SHOW_WITHIN_MS;
+  while (Date.now() < deadline) {
+    if ((await fetchPage(origin, path)).html.includes(needle)) {
+      return true;
+    }
+    await new Promise((resolve) => setTimeout(resolve, POLL_EVERY_MS));
+  }
+  return false;
+};
+
+/** Saves (does not publish) the article's English title, and returns a function that puts the old one back. */
+const saveTitle = async (client: Awaited<ReturnType<typeof connectAdmin>>['client'], title: string) => {
+  const [item] = (
+    await client.admin.content.list('article', { locale: 'en', filters: { slug: { $eq: ARTICLE } } })
+  ).items;
+  if (!item) {
+    throw new Error(`The seeded article "${ARTICLE}" is missing; run npm run seed first`);
+  }
+  const entry = await client.admin.content.get('article', item.id, { locale: 'en' });
+  const original = entry.data.title;
+  // A save sends only the fields it changes.
+  const saved = await client.admin.content.update('article', item.id, {
+    locale: 'en',
+    expectedVersion: entry.version,
+    data: { title },
+  });
+  return async () => {
+    await client.admin.content.update('article', item.id, {
+      locale: 'en',
+      expectedVersion: saved.version,
+      data: { title: original },
+    });
+  };
+};
+
+const main = async () => {
+  const { values } = parseArgs({ options: { url: { type: 'string' } } });
+  const origin = values.url ?? process.env.SMOKE_URL ?? 'http://localhost:3000';
+
+  const list = await fetchPage(origin, '/en/articles/');
+  check(list.status === 200, `/en/articles/: HTTP ${list.status}`);
+  check(list.html.includes(BADGE), '/en/articles/: the Drafts badge');
+  check(list.html.includes(DRAFT_TITLE), 'the unpublished draft is listed (drafts mode)');
+  const draft = await fetchPage(origin, '/en/articles/winter-projects/');
+  check(
+    draft.status === 200 && draft.html.includes(DRAFT_TITLE),
+    `the unpublished draft is served (HTTP ${draft.status})`,
+  );
+
+  const admin = await connectAdmin(process.env);
+  try {
+    const marker = `Saved, not published ${Date.now()}`;
+    const restore = await saveTitle(admin.client, marker);
+    try {
+      check(
+        await showsWithin(origin, `/en/articles/${ARTICLE}/`, marker),
+        'a change saved in Shapio shows on reload, without publishing',
+      );
+    } finally {
+      await restore();
+    }
+  } finally {
+    await admin.close();
+  }
+
+  if (failures.length > 0) {
+    throw new Error(`${failures.length} check(s) failed against ${origin}`);
+  }
+  process.stdout.write(`Drafts smoke test passed against ${origin}.\n`);
+};
+
+main().catch((error: unknown) => {
+  process.stderr.write(`smoke:drafts: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+});

package/templates/astro/src/layouts/Base.astro

@@ -1,6 +1,7 @@
 ---
 import '../styles/site.css';
 import type { SeoResolved } from '@shapio/client';
+import { isDraftsMode } from '../lib/config.js';
 import { seoHead, type SeoHead } from '../lib/seo.js';
 import { getSite, getSiteSettings } from '../lib/shapio.js';
 import {
@@ -90,5 +91,12 @@ const robotsNoindex = noindex || head.noindex;
     <footer class="site-footer">
       <p>{siteName} · {settings?.footer ?? 'Built with Shapio'} · Astro</p>
     </footer>
+    {
+      isDraftsMode() ? (
+        <p class="drafts-badge" title={strings.draftsNote} data-shapio-drafts="">
+          {strings.drafts}
+        </p>
+      ) : null
+    }
   </body>
 </html>

package/templates/astro/src/lib/config.ts

@@ -6,6 +6,10 @@
  *   without it the build pins the latest snapshot when it starts.
  * - SHAPIO_SITE: optional; the site key on a multi-site Shapio (default: the token's site, else the primary).
  * - PUBLIC_SHAPIO_URL: the origin the browser calls for previews (defaults to SHAPIO_URL).
+ * - SHAPIO_DRAFTS: `true` turns on drafts mode, for your development server: every read shows saved drafts
+ *   instead of published content (no snapshot), and pages carry a "Drafts" badge. The token must be a delivery
+ *   token whose role grants Read drafts: SHAPIO_DEV_DELIVERY_TOKEN when set (`npm run seed` writes one), else
+ *   SHAPIO_DELIVERY_TOKEN. Never set it in a production environment.
  */
 const read = (name: string): string | undefined => {
   const fromVite = (import.meta as { env?: Record<string, string | undefined> }).env?.[name];
@@ -15,8 +19,13 @@ const read = (name: string): string | undefined => {
 
 export const shapioUrl = () => read('SHAPIO_URL') ?? 'http://localhost:4300';
 
+/** Drafts mode (SHAPIO_DRAFTS=true): the site reads saved drafts. Never set in production. */
+export const isDraftsMode = () => read('SHAPIO_DRAFTS') === 'true';
+
 export const deliveryToken = () => {
-  const token = read('SHAPIO_DELIVERY_TOKEN');
+  // Drafts mode reads with the development token (Read drafts) when there is one.
+  const token =
+    (isDraftsMode() ? read('SHAPIO_DEV_DELIVERY_TOKEN') : undefined) ?? read('SHAPIO_DELIVERY_TOKEN');
   if (!token) {
     throw new Error(
       'Set SHAPIO_DELIVERY_TOKEN (a Shapio delivery token) to build the site; `npm run seed` writes one to .env',
@@ -40,3 +49,6 @@ export const configuredSnapshot = (): number | undefined => {
 export const publicShapioUrl = () => read('PUBLIC_SHAPIO_URL') ?? shapioUrl();
 
 export const siteKey = () => read('SHAPIO_SITE');
+
+/** True under `astro dev` (Vite's import.meta.env.DEV); false in builds and in the scripts. */
+export const isDev = () => (import.meta as { env?: { DEV?: boolean } }).env?.DEV === true;

package/templates/astro/src/lib/renderTime.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it, vi } from 'vitest';
+import { findBySlug, renderTimeEntry } from './renderTime.js';
+
+describe('renderTimeEntry', () => {
+  it('renders the getStaticPaths props in a build, without reading', async () => {
+    const read = vi.fn();
+    expect(await renderTimeEntry({ dev: false, props: { slug: 'about' }, read })).toEqual({ slug: 'about' });
+    expect(read).not.toHaveBeenCalled();
+  });
+
+  it('reads the entry when it renders in dev, over stale props', async () => {
+    const read = vi.fn().mockResolvedValue({ slug: 'about', title: 'New' });
+    expect(await renderTimeEntry({ dev: true, props: { slug: 'about', title: 'Old' }, read })).toEqual({
+      slug: 'about',
+      title: 'New',
+    });
+  });
+
+  it('is undefined in dev when the entry is gone, so the page answers 404', async () => {
+    const read = vi.fn().mockResolvedValue(undefined);
+    expect(await renderTimeEntry({ dev: true, props: { slug: 'about' }, read })).toBeUndefined();
+  });
+});
+
+describe('findBySlug', () => {
+  it('finds the entry with the slug, or nothing', () => {
+    const entries = [{ slug: 'home' }, { slug: 'about' }];
+    expect(findBySlug(entries, 'about')).toBe(entries[1]);
+    expect(findBySlug(entries, 'gone')).toBeUndefined();
+  });
+});

package/templates/astro/src/lib/renderTime.ts

@@ -0,0 +1,24 @@
+/**
+ * What a dynamic page renders. A build renders what getStaticPaths handed over as props (every page at the
+ * build's one snapshot). `astro dev` keeps getStaticPaths results until it restarts, so there the page reads
+ * its entry from Shapio when it renders, from `Astro.params`: a publish shows on reload, and an entry that is
+ * gone (unpublished or deleted) is undefined, which the page answers with a 404.
+ */
+type RenderTimeSource<T> = {
+  /** True under `astro dev`. */
+  dev: boolean;
+  /** What getStaticPaths handed over. */
+  props: T | undefined;
+  /** Reads the entry now; undefined when it is not published. */
+  read: () => Promise<T | undefined>;
+};
+
+export const renderTimeEntry = async <T>({
+  dev,
+  props,
+  read,
+}: RenderTimeSource<T>): Promise<T | undefined> => (dev ? read() : props);
+
+/** The entry with this slug, if any. */
+export const findBySlug = <T extends { slug: string }>(entries: readonly T[], slug: string): T | undefined =>
+  entries.find((entry) => entry.slug === slug);

package/templates/astro/src/lib/shapio.ts

@@ -1,13 +1,16 @@
-import { createClient, ShapioApiError, type DeliverySite } from '@shapio/client';
-import { configuredSnapshot, deliveryToken, shapioUrl, siteKey } from './config.js';
+import { createClient, ShapioApiError, type DeliveryListQuery, type DeliverySite } from '@shapio/client';
+import { configuredSnapshot, deliveryToken, isDev, isDraftsMode, shapioUrl, siteKey } from './config.js';
 import type { Locale } from './site.js';
-import type { Article, DeliveryList, Page, SiteSettings } from './types.js';
+import { cachedRead, cacheWindow, createSnapshotResolver } from './snapshotResolver.js';
+import type { Article, Page, SiteSettings } from './types.js';
 
 /**
  * The site's read side: Shapio's delivery API through `@shapio/client`, pinned to one publication snapshot
  * for the whole build. The snapshot is read once, when the build starts (or taken from SHAPIO_SNAPSHOT), and
  * sent with every request, so a page built a minute later still shows the same moment: a publish during the
- * build never yields a site that mixes old and new content.
+ * build never yields a site that mixes old and new content. Under `astro dev` the snapshot and the site settings
+ * are read again once the last read is a second old, so a publish shows on reload (src/lib/snapshotResolver.ts).
+ * Drafts mode (SHAPIO_DRAFTS=true) reads saved drafts, which have no snapshot: no read sends one.
  */
 const PAGE_SIZE = 100;
 
@@ -19,8 +22,8 @@ const ARTICLES = 'articles';
  * The fields each listing renders, sent as `fields=`: the response carries only these, and Shapio's field
  * usage shows exactly what the site reads (a whole-model read would count every field as used).
  */
-const PAGE_FIELDS = 'title,slug,description,sections,seo';
-const ARTICLE_FIELDS = 'title,slug,excerpt,body,cover,author,publishedOn,seo';
+const PAGE_FIELDS = ['title', 'slug', 'description', 'sections', 'seo'];
+const ARTICLE_FIELDS = ['title', 'slug', 'excerpt', 'body', 'cover', 'author', 'publishedOn', 'seo'];
 
 /** The `siteSettings` singleton is read by its API ID (singletons have no plural). */
 const SITE_SETTINGS = 'siteSettings';
@@ -28,40 +31,54 @@ const SITE_SETTINGS_FIELDS = ['siteName', 'tagline', 'footer', 'colophon'];
 
 let client: ReturnType<typeof createClient> | undefined;
 const shapio = () =>
-  (client ??= createClient({ baseUrl: shapioUrl(), token: deliveryToken(), site: siteKey() }));
+  (client ??= createClient({
+    baseUrl: shapioUrl(),
+    token: deliveryToken(),
+    site: siteKey(),
+    drafts: isDraftsMode(),
+  }));
 
-let pinned: Promise<number> | undefined;
+let resolver: (() => Promise<number>) | undefined;
 
-/** The snapshot every request of this build reads. */
-export const pinnedSnapshot = (): Promise<number> =>
-  (pinned ??= (async () => {
-    const configured = configuredSnapshot();
-    if (configured !== undefined) {
-      return configured;
-    }
-    const { snapshot } = await shapio().snapshots.current();
-    // Shared with any other copy of this module in the build (one value per build).
-    process.env.SHAPIO_SNAPSHOT = String(snapshot);
-    return snapshot;
-  })());
-
-const query = (params: Record<string, string | number>) =>
-  new URLSearchParams(Object.entries(params).map(([key, value]) => [key, String(value)])).toString();
+/**
+ * The snapshot every request reads: one for the whole build; in dev, the current one (re-read after 1 s); in
+ * drafts mode, none (drafts cannot be pinned).
+ */
+export const pinnedSnapshot = async (): Promise<number | undefined> => {
+  if (isDraftsMode()) {
+    return undefined;
+  }
+  const dev = isDev();
+  resolver ??= createSnapshotResolver({
+    dev,
+    configured: configuredSnapshot(),
+    current: async () => {
+      const { snapshot } = await shapio().snapshots.current();
+      if (!dev) {
+        // Shared with any other copy of this module in the build (one value per build).
+        process.env.SHAPIO_SNAPSHOT = String(snapshot);
+      }
+      return snapshot;
+    },
+  });
+  return resolver();
+};
 
 /** Every published entry of a collection (by plural API ID) in one locale, page by page, at the pinned snapshot. */
-const listAll = async <T>(
-  routeKey: string,
-  locale: Locale,
-  extra: Record<string, string> = {},
-): Promise<T[]> => {
+const listAll = async <T>(routeKey: string, query: DeliveryListQuery): Promise<T[]> => {
   const snapshot = await pinnedSnapshot();
   const entries: T[] = [];
   for (let page = 1; ; page += 1) {
-    const result = await shapio().request<DeliveryList<T>>(
+    const result = await shapio().delivery.list<T>(routeKey, {
+      ...query,
       // The site renders the server's sanitized HTML, so it asks for that instead of the JSON document, and
       // its SEO fields with the site's defaults filled in (`seo=resolved`).
-      `/api/content/${routeKey}?${query({ locale, snapshot, page, pageSize: PAGE_SIZE, richText: 'html', seo: 'resolved', ...extra })}`,
-    );
+      richText: 'html',
+      seo: 'resolved',
+      snapshot,
+      page,
+      pageSize: PAGE_SIZE,
+    });
     entries.push(...result.data);
     if (page >= result.meta.pagination.pageCount) {
       return entries;
@@ -69,55 +86,62 @@ const listAll = async <T>(
   }
 };
 
-export const listPages = (locale: Locale) => listAll<Page>(PAGES, locale, { fields: PAGE_FIELDS });
+export const listPages = (locale: Locale) => listAll<Page>(PAGES, { locale, fields: PAGE_FIELDS });
 
 export const listArticles = (locale: Locale) =>
-  listAll<Article>(ARTICLES, locale, {
+  listAll<Article>(ARTICLES, {
+    locale,
     fields: ARTICLE_FIELDS,
-    populate: 'author',
-    sort: 'publishedOn:desc',
+    populate: ['author'],
+    sort: [{ field: 'publishedOn', direction: 'desc' }],
   });
 
-const settingsByLocale = new Map<Locale, Promise<SiteSettings | null>>();
+const readSiteSettings = async (locale: Locale): Promise<SiteSettings | null> => {
+  try {
+    const { data } = await shapio().delivery.singleton<SiteSettings>(SITE_SETTINGS, {
+      locale,
+      snapshot: await pinnedSnapshot(),
+      fields: SITE_SETTINGS_FIELDS,
+      richText: 'html',
+    });
+    return data;
+  } catch (error) {
+    if (error instanceof ShapioApiError && error.status === 404) {
+      return null;
+    }
+    throw error;
+  }
+};
+
+const settingsByLocale = new Map<Locale, () => Promise<SiteSettings | null>>();
 
 /** The site settings singleton in one locale at the pinned snapshot; null until it is published. */
 export const getSiteSettings = (locale: Locale): Promise<SiteSettings | null> => {
   let settings = settingsByLocale.get(locale);
   if (!settings) {
-    settings = (async () => {
-      try {
-        const snapshot = await pinnedSnapshot();
-        const { data } = await shapio().delivery.singleton<SiteSettings>(SITE_SETTINGS, {
-          locale,
-          snapshot,
-          fields: SITE_SETTINGS_FIELDS,
-          richText: 'html',
-        });
-        return data;
-      } catch (error) {
-        if (error instanceof ShapioApiError && error.status === 404) {
-          return null;
-        }
-        throw error;
-      }
-    })();
+    settings = cachedRead(() => readSiteSettings(locale), cacheWindow(isDev()));
     settingsByLocale.set(locale, settings);
   }
-  return settings;
+  return settings();
 };
 
-let site: Promise<DeliverySite | null> | undefined;
+const readSite = async (): Promise<DeliverySite | null> => {
+  try {
+    return await shapio().site.get();
+  } catch (error) {
+    if (error instanceof ShapioApiError && error.status === 404) {
+      return null;
+    }
+    throw error;
+  }
+};
+
+let site: (() => Promise<DeliverySite | null>) | undefined;
 
 /**
  * The site and its SEO defaults (name and title template per locale, default image, Twitter handle), once per
- * build. Null when the Shapio predates them: the pages still render, with plain titles.
+ * build (in dev, re-read after 1 s). Null when the Shapio predates them: the pages still render, with plain
+ * titles.
  */
 export const getSite = (): Promise<DeliverySite | null> =>
-  (site ??= shapio()
-    .site.get()
-    .catch((error: unknown) => {
-      if (error instanceof ShapioApiError && error.status === 404) {
-        return null;
-      }
-      throw error;
-    }));
+  (site ??= cachedRead(readSite, cacheWindow(isDev())))();