create-shapio 0.5.0 → 0.5.2

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

@@ -0,0 +1,63 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { buildEnvKey, cacheKeyOf } from './cacheKey.js';
+
+describe('cacheKeyOf', () => {
+  it('is a 32-character hex digest', () => {
+    expect(cacheKeyOf({ title: 'Hello' })).toMatch(/^[0-9a-f]{32}$/);
+  });
+
+  it('does not depend on the order of object keys, at any depth', () => {
+    expect(cacheKeyOf({ a: 1, b: { c: 2, d: [{ e: 3, f: 4 }] } })).toBe(
+      cacheKeyOf({ b: { d: [{ f: 4, e: 3 }], c: 2 }, a: 1 }),
+    );
+  });
+
+  it('changes when any nested value changes', () => {
+    const page = { title: 'Home', sections: [{ heading: 'Hi', image: { url: '/a.webp' } }] };
+    const edited = { title: 'Home', sections: [{ heading: 'Hi', image: { url: '/b.webp' } }] };
+    expect(cacheKeyOf(page)).not.toBe(cacheKeyOf(edited));
+  });
+
+  it('is sensitive to array order', () => {
+    expect(cacheKeyOf([1, 2])).not.toBe(cacheKeyOf([2, 1]));
+  });
+
+  it('tells its inputs apart (a value moved from one argument to the next is a different key)', () => {
+    expect(cacheKeyOf({ a: 1 }, { b: 2 })).not.toBe(cacheKeyOf({ a: 1, b: 2 }));
+  });
+
+  it('reads undefined as null and a date as its ISO text', () => {
+    expect(cacheKeyOf({ a: undefined })).toBe(cacheKeyOf({ a: null }));
+    expect(cacheKeyOf({ at: new Date('2026-10-07T00:00:00.000Z') })).toBe(
+      cacheKeyOf({ at: '2026-10-07T00:00:00.000Z' }),
+    );
+  });
+
+  it('throws on what is not plain data, naming where it is', () => {
+    expect(() => cacheKeyOf({ render: () => '' })).toThrow('inputs[0].render is a function');
+    expect(() => cacheKeyOf({ id: Symbol('x') })).toThrow('is a symbol');
+    expect(() => cacheKeyOf({ size: 1n })).toThrow('is a bigint');
+    expect(() => cacheKeyOf({ tags: new Set(['a']) })).toThrow('is a Set');
+  });
+
+  it('throws on a value that refers back to itself, but accepts the same object twice', () => {
+    const shared = { name: 'Ada' };
+    expect(() => cacheKeyOf({ author: shared, editor: shared })).not.toThrow();
+    const loop: Record<string, unknown> = {};
+    loop.self = loop;
+    expect(() => cacheKeyOf(loop)).toThrow('refers back to itself');
+  });
+});
+
+describe('buildEnvKey', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it('carries drafts mode and the year, which a page shows without reading them from its data', () => {
+    vi.stubEnv('SHAPIO_DRAFTS', 'true');
+    expect(buildEnvKey()).toEqual({ drafts: true, year: new Date().getFullYear() });
+    vi.stubEnv('SHAPIO_DRAFTS', '');
+    expect(buildEnvKey().drafts).toBe(false);
+  });
+});

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

@@ -0,0 +1,57 @@
+import { createHash } from 'node:crypto';
+import { isDraftsMode } from './config.js';
+
+/**
+ * Keys for Astro's incremental build (`experimental.incrementalBuild` in astro.config.mjs). A page returned by
+ * `getStaticPaths()` with a `cacheKey` is restored from the previous build, not rendered, when its key and its
+ * code (Astro hashes the page's import graph) are both unchanged. So the key must cover every piece of data the
+ * page renders: its props, what the layout reads (`layoutInputs`), and the build environment (`buildEnvKey`).
+ * Whole objects go in, never a hand-picked list of fields, which would drift from what the page renders.
+ */
+
+/** Plain data in a stable form: object keys sorted, arrays in order, `undefined` as null, dates as ISO text. */
+const normalize = (value: unknown, path: string, seen: Set<object>): unknown => {
+  if (value === undefined || value === null) {
+    return null;
+  }
+  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+    return value;
+  }
+  if (typeof value === 'function' || typeof value === 'symbol' || typeof value === 'bigint') {
+    throw new TypeError(`cacheKeyOf: ${path} is a ${typeof value}, not plain data`);
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  const object = value;
+  if (seen.has(object)) {
+    throw new TypeError(`cacheKeyOf: ${path} refers back to itself`);
+  }
+  seen.add(object);
+  try {
+    if (Array.isArray(object)) {
+      return object.map((item, index) => normalize(item, `${path}[${index}]`, seen));
+    }
+    const prototype = Object.getPrototypeOf(object) as unknown;
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new TypeError(`cacheKeyOf: ${path} is a ${object.constructor.name}, not plain data`);
+    }
+    const entries = Object.entries(object).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return Object.fromEntries(entries.map(([key, item]) => [key, normalize(item, `${path}.${key}`, seen)]));
+  } finally {
+    seen.delete(object);
+  }
+};
+
+/** A stable digest of the data a page renders: same inputs, same key, whatever the order of object keys. */
+export const cacheKeyOf = (...inputs: unknown[]): string =>
+  createHash('sha256')
+    .update(JSON.stringify(normalize(inputs, 'inputs', new Set())))
+    .digest('hex')
+    .slice(0, 32);
+
+/**
+ * What a page shows that comes from neither its data nor its code: settings read from the environment and the
+ * clock when it renders, which Astro's code and config hashes do not see.
+ */
+export const buildEnvKey = () => ({ drafts: isDraftsMode(), year: new Date().getFullYear() });

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

@@ -6,17 +6,29 @@
  *   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.
+ *
+ * Settings come from `process.env` only (astro.config.mjs loads `.env` into it). Reading Vite's env object as a
+ * whole instead would make Vite write every variable named in this file into the compiled code, so a changed
+ * SHAPIO_SNAPSHOT would change the code Astro hashes and re-render every page (see src/lib/cacheKey.ts).
  */
 const read = (name: string): string | undefined => {
-  const fromVite = (import.meta as { env?: Record<string, string | undefined> }).env?.[name];
-  const value = fromVite ?? process.env[name];
+  const value = process.env[name];
   return value === undefined || value === '' ? undefined : value;
 };
 
 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 +52,21 @@ export const configuredSnapshot = (): number | undefined => {
 export const publicShapioUrl = () => read('PUBLIC_SHAPIO_URL') ?? shapioUrl();
 
 export const siteKey = () => read('SHAPIO_SITE');
+
+type ViteImportMeta = ImportMeta & { env: { DEV?: boolean } };
+
+/**
+ * True under `astro dev`; false in builds and in the scripts. Written out in full (`import.meta.env.DEV`) so Vite
+ * replaces it with a constant; outside Vite (the scripts, run by Node) there is no env object, which is the
+ * TypeError caught here, and that is not dev.
+ */
+export const isDev = (): boolean => {
+  try {
+    return (import.meta as ViteImportMeta).env.DEV === true;
+  } catch (error) {
+    if (error instanceof TypeError) {
+      return false;
+    }
+    throw error;
+  }
+};

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

@@ -0,0 +1,13 @@
+import { buildEnvKey } from './cacheKey.js';
+import { getSite, getSiteSettings } from './shapio.js';
+import type { Locale } from './site.js';
+
+/**
+ * Everything layouts/Base.astro reads when it renders, besides its props: the site settings and the site's SEO
+ * defaults (both read once per build) and the build environment. The layout reads through this function and
+ * every keyed page folds it into its `cacheKey`, so a read added to the layout is in the key too.
+ */
+export const layoutInputs = async (locale: Locale) => {
+  const [settings, site] = await Promise.all([getSiteSettings(locale), getSite()]);
+  return { settings, site, env: buildEnvKey() };
+};

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())))();

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

@@ -22,6 +22,8 @@ const STRINGS = {
     previewLoading: 'Loading the draft…',
     previewFailed: 'The preview could not be loaded',
     skipToContent: 'Skip to content',
+    drafts: 'Drafts',
+    draftsNote: 'Drafts mode: this server shows saved drafts, not the published site.',
   },
   fr: {
     siteName: 'Studio Northwind',
@@ -36,6 +38,8 @@ const STRINGS = {
     previewLoading: 'Chargement du brouillon…',
     previewFailed: "L'aperçu n'a pas pu être chargé",
     skipToContent: 'Aller au contenu',
+    drafts: 'Brouillons',
+    draftsNote: 'Mode brouillons : ce serveur montre les brouillons enregistrés, pas le site publié.',
   },
 } as const satisfies Record<Locale, Record<string, string>>;
 

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

@@ -0,0 +1,64 @@
+import { describe, expect, it, vi } from 'vitest';
+import { cachedRead, createSnapshotResolver, DEV_WINDOW_MS } from './snapshotResolver.js';
+
+const clock = (start = 0) => {
+  let time = start;
+  return { now: () => time, advance: (ms: number) => (time += ms) };
+};
+
+describe('createSnapshotResolver', () => {
+  it('pins the first snapshot for the whole build', async () => {
+    const { now, advance } = clock();
+    const current = vi.fn().mockResolvedValueOnce(7).mockResolvedValue(8);
+    const snapshot = createSnapshotResolver({ dev: false, configured: undefined, current, now });
+
+    expect(await snapshot()).toBe(7);
+    advance(60 * 60 * 1000);
+    expect(await snapshot()).toBe(7);
+    expect(current).toHaveBeenCalledTimes(1);
+  });
+
+  it('reuses a dev read within the window and reads the current snapshot again after it', async () => {
+    const { now, advance } = clock();
+    const current = vi.fn().mockResolvedValueOnce(7).mockResolvedValue(8);
+    const snapshot = createSnapshotResolver({ dev: true, configured: undefined, current, now });
+
+    expect(await snapshot()).toBe(7);
+    advance(DEV_WINDOW_MS - 1);
+    expect(await snapshot()).toBe(7);
+    expect(current).toHaveBeenCalledTimes(1);
+
+    advance(1);
+    expect(await snapshot()).toBe(8);
+    expect(current).toHaveBeenCalledTimes(2);
+  });
+
+  it('keeps SHAPIO_SNAPSHOT in dev and in builds, without asking Shapio', async () => {
+    const current = vi.fn().mockResolvedValue(8);
+    for (const dev of [true, false]) {
+      const snapshot = createSnapshotResolver({ dev, configured: 3, current });
+      expect(await snapshot()).toBe(3);
+    }
+    expect(current).not.toHaveBeenCalled();
+  });
+});
+
+describe('cachedRead', () => {
+  it('shares one read between calls that overlap it', async () => {
+    const read = vi.fn().mockResolvedValue('value');
+    const cached = cachedRead(read, DEV_WINDOW_MS, clock().now);
+
+    const [first, second] = await Promise.all([cached(), cached()]);
+    expect([first, second]).toEqual(['value', 'value']);
+    expect(read).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not keep a failed read', async () => {
+    const read = vi.fn().mockRejectedValueOnce(new Error('down')).mockResolvedValue('value');
+    const cached = cachedRead(read, Number.POSITIVE_INFINITY, clock().now);
+
+    await expect(cached()).rejects.toThrow('down');
+    expect(await cached()).toBe('value');
+    expect(read).toHaveBeenCalledTimes(2);
+  });
+});

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

@@ -0,0 +1,52 @@
+/**
+ * Which publication snapshot the site reads, and for how long a read is reused. A build pins one snapshot
+ * for all its pages (SHAPIO_SNAPSHOT, else the current one when the build starts). The dev server reads the
+ * current snapshot again once the last read is older than DEV_WINDOW_MS, so a publish shows on reload while
+ * the reads of one page render still share a snapshot.
+ */
+export const DEV_WINDOW_MS = 1000;
+
+/** How long a cached read is reused: for the whole process in a build, DEV_WINDOW_MS in dev. */
+export const cacheWindow = (dev: boolean): number => (dev ? DEV_WINDOW_MS : Number.POSITIVE_INFINITY);
+
+/** `read`, reused for `windowMs` after it starts. A read that fails is not kept: the next call tries again. */
+export const cachedRead = <T>(
+  read: () => Promise<T>,
+  windowMs: number,
+  now: () => number = Date.now,
+): (() => Promise<T>) => {
+  let cached: { value: Promise<T>; at: number } | undefined;
+  return () => {
+    const at = now();
+    if (cached && at - cached.at < windowMs) {
+      return cached.value;
+    }
+    const entry = { value: read(), at };
+    cached = entry;
+    entry.value.catch(() => {
+      if (cached === entry) {
+        cached = undefined;
+      }
+    });
+    return entry.value;
+  };
+};
+
+type SnapshotResolverOptions = {
+  /** True under the dev server. */
+  dev: boolean;
+  /** SHAPIO_SNAPSHOT: when set, the site shows exactly this snapshot, in dev too. */
+  configured: number | undefined;
+  /** Reads Shapio's current publication snapshot. */
+  current: () => Promise<number>;
+  now?: () => number;
+};
+
+/** The snapshot every delivery read sends. */
+export const createSnapshotResolver = ({
+  dev,
+  configured,
+  current,
+  now,
+}: SnapshotResolverOptions): (() => Promise<number>) =>
+  configured === undefined ? cachedRead(current, cacheWindow(dev), now) : () => Promise.resolve(configured);

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

@@ -91,13 +91,4 @@ export type SiteSettings = EntryBase & {
   colophon: RichText | null;
 };
 
-export type DeliveryList<T> = {
-  data: T[];
-  meta: {
-    locale: string;
-    snapshot: number;
-    pagination: { page: number; pageSize: number; total: number; pageCount: number };
-  };
-};
-
 export type DeliveryItem<T> = { data: T; meta: { locale: string; snapshot: number } };

package/templates/astro/src/pages/[locale]/[...slug].astro

@@ -1,18 +1,29 @@
 ---
 import Base from '../../layouts/Base.astro';
+import { cacheKeyOf } from '../../lib/cacheKey.js';
+import { isDev } from '../../lib/config.js';
+import { layoutInputs } from '../../lib/layoutInputs.js';
 import { renderPage } from '../../lib/render.js';
+import { findBySlug, renderTimeEntry } from '../../lib/renderTime.js';
 import { listPages } from '../../lib/shapio.js';
 import { HOME_SLUG, LOCALES, otherLocale, pagePath, type Locale } from '../../lib/site.js';
 import type { Page } from '../../lib/types.js';
 
-/** Every published page in every locale; `home` is the locale's front page (`/en/`, `/fr/`). */
+/**
+ * Every published page in every locale; `home` is the locale's front page (`/en/`, `/fr/`). The page renders
+ * only its props and what the layout reads, so those are its cacheKey: a build restores it from the previous
+ * build while they are unchanged (src/lib/cacheKey.ts).
+ */
 export const getStaticPaths = async () => {
   const paths = [];
   for (const locale of LOCALES) {
+    const layout = await layoutInputs(locale);
     for (const page of await listPages(locale)) {
+      const props = { page, locale };
       paths.push({
         params: { locale, slug: page.slug === HOME_SLUG ? undefined : page.slug },
-        props: { page, locale },
+        props,
+        cacheKey: cacheKeyOf(props, layout),
       });
     }
   }
@@ -20,7 +31,16 @@ export const getStaticPaths = async () => {
 };
 
 type Props = { page: Page; locale: Locale };
-const { page, locale } = Astro.props;
+const { locale } = Astro.props;
+// In `astro dev`, read at render time (src/lib/renderTime.ts); a build renders the props above.
+const page = await renderTimeEntry({
+  dev: isDev(),
+  props: Astro.props.page,
+  read: async () => findBySlug(await listPages(locale), Astro.params.slug ?? HOME_SLUG),
+});
+if (!page) {
+  return Astro.rewrite('/404/');
+}
 ---
 
 <Base title={page.title} seo={page.seo} locale={locale} alternatePath={pagePath(otherLocale(locale), page.slug)}>