create-shapio 0.5.0 → 0.5.1

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,6 +1,8 @@
 ---
 import Base from '../../layouts/Base.astro';
+import { isDev } from '../../lib/config.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';
@@ -20,7 +22,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)}>

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

@@ -1,6 +1,8 @@
 ---
 import Base from '../../../layouts/Base.astro';
+import { isDev } from '../../../lib/config.js';
 import { renderArticle } from '../../../lib/render.js';
+import { findBySlug, renderTimeEntry } from '../../../lib/renderTime.js';
 import { listArticles } from '../../../lib/shapio.js';
 import { articlePath, LOCALES, otherLocale, stringsFor, type Locale } from '../../../lib/site.js';
 import type { Article } from '../../../lib/types.js';
@@ -16,7 +18,16 @@ export const getStaticPaths = async () => {
 };
 
 type Props = { locale: Locale; article: Article };
-const { locale, article } = Astro.props;
+const { locale } = Astro.props;
+// In `astro dev`, read at render time (src/lib/renderTime.ts); a build renders the props above.
+const article = await renderTimeEntry({
+  dev: isDev(),
+  props: Astro.props.article,
+  read: async () => findBySlug(await listArticles(locale), Astro.params.slug ?? ''),
+});
+if (!article) {
+  return Astro.rewrite('/404/');
+}
 const context = { locale, strings: stringsFor(locale) };
 ---
 

package/templates/astro/src/pages/[locale]/articles/index.astro

@@ -1,6 +1,8 @@
 ---
 import Base from '../../../layouts/Base.astro';
+import { isDev } from '../../../lib/config.js';
 import { renderArticleCard } from '../../../lib/render.js';
+import { renderTimeEntry } from '../../../lib/renderTime.js';
 import { listArticles } from '../../../lib/shapio.js';
 import { articlesPath, LOCALES, otherLocale, stringsFor, type Locale } from '../../../lib/site.js';
 import type { Article } from '../../../lib/types.js';
@@ -11,7 +13,10 @@ export const getStaticPaths = async () =>
   );
 
 type Props = { locale: Locale; articles: Article[] };
-const { locale, articles } = Astro.props;
+const { locale } = Astro.props;
+// In `astro dev`, read at render time (src/lib/renderTime.ts); a build renders the props above.
+const articles =
+  (await renderTimeEntry({ dev: isDev(), props: Astro.props.articles, read: () => listArticles(locale) })) ?? [];
 const strings = stringsFor(locale);
 const context = { locale, strings };
 ---

package/templates/astro/src/pages/build.json.ts

@@ -1,9 +1,16 @@
 import { pinnedSnapshot } from '../lib/shapio.js';
 import { LOCALES } from '../lib/site.js';
 
-/** `/build.json`: which publication snapshot this build shows (for checks and deployment debugging). */
+/**
+ * `/build.json`: which publication snapshot this build shows (for checks and deployment debugging); null in
+ * drafts mode, which shows saved drafts.
+ */
 export const GET = async () =>
   new Response(
-    JSON.stringify({ snapshot: await pinnedSnapshot(), locales: LOCALES, builtAt: new Date().toISOString() }),
+    JSON.stringify({
+      snapshot: (await pinnedSnapshot()) ?? null,
+      locales: LOCALES,
+      builtAt: new Date().toISOString(),
+    }),
     { headers: { 'content-type': 'application/json' } },
   );

package/templates/astro/src/styles/site.css

@@ -197,3 +197,17 @@ main {
   text-align: center;
   font-weight: 600;
 }
+/* Drafts mode (SHAPIO_DRAFTS=true): a corner badge, so a drafts build is never mistaken for the real site. */
+.drafts-badge {
+  position: fixed;
+  right: 1rem;
+  bottom: 1rem;
+  z-index: 10;
+  margin: 0;
+  background: #78350f;
+  color: #fef3c7;
+  padding: 0.25rem 0.75rem;
+  border-radius: 999px;
+  font-size: 0.875rem;
+  font-weight: 700;
+}

package/templates/next/.env.example

@@ -19,3 +19,9 @@ NEXT_TELEMETRY_DISABLED=1
 # Shapio's own database. A read-only database role is enough. Previews still use SHAPIO_URL.
 # SHAPIO_MODE=in-process
 # DATABASE_URL=postgres://shapio_site:password@localhost:5432/shapio
+# 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/next/README.md

@@ -34,6 +34,15 @@ instance. Next.js telemetry is off: `NEXT_TELEMETRY_DISABLED=1` in the npm scrip
 | `src/lib/revalidation*.ts`   | the snapshot diff, and which pages and cache tags a change touches |
 | `shapio/`, `scripts/seed.ts` | the models and the seed                                            |
 
+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:3000; 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:3000/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/next/next.config.ts

@@ -7,12 +7,16 @@ import { createShapioClient } from './src/lib/shapioClient';
  * the snapshot is read here, once, before any page renders, and handed to every worker as SHAPIO_SNAPSHOT
  * (inlined into the build). A set SHAPIO_SNAPSHOT wins and pins the site for good; otherwise `next start` moves
  * forward from this snapshot as Shapio's webhook calls /api/revalidate (src/lib/liveSnapshot.ts). `next dev` and
- * `next start` do not read Shapio here.
+ * `next start` do not read Shapio here. Drafts mode (SHAPIO_DRAFTS=true) pins nothing: drafts have no
+ * snapshot.
  */
 const pinSnapshot = async (): Promise<string> => {
   if (process.env.SHAPIO_SNAPSHOT) {
     return process.env.SHAPIO_SNAPSHOT;
   }
+  if (process.env.SHAPIO_DRAFTS === 'true') {
+    return '';
+  }
   // Over HTTP or in process, as the pages read (SHAPIO_MODE).
   const client = createShapioClient();
   try {

package/templates/next/package.json

@@ -13,13 +13,14 @@
     "start": "NEXT_TELEMETRY_DISABLED=1 next start",
     "seed": "node --env-file-if-exists=.env --import tsx scripts/seed.ts --site-url http://localhost:3000 --revalidate-path /api/revalidate/",
     "smoke": "node --env-file-if-exists=.env --import tsx scripts/smokeHttp.ts --url http://localhost:3000",
+    "smoke:drafts": "node --env-file-if-exists=.env --import tsx scripts/smokeDrafts.ts --url http://localhost:3000",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "vitest run"
   },
   "dependencies": {
-    "@shapio/client": "^0.5.0",
-    "@shapio/local": "0.5.0",
-    "@shapio/visual": "^0.5.0",
+    "@shapio/client": "^0.5.1",
+    "@shapio/local": "0.5.1",
+    "@shapio/visual": "^0.5.1",
     "next": "16.3.8",
     "react": "19.3.0",
     "react-dom": "19.3.0"

package/templates/next/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/next/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/next/src/app/[locale]/layout.tsx

@@ -2,7 +2,9 @@ import type { Metadata } from 'next';
 import Link from 'next/link';
 import { notFound } from 'next/navigation';
 import type { ReactNode } from 'react';
+import { DraftsBadge } from '../../components/DraftsBadge';
 import { LocaleSwitch } from '../../components/LocaleSwitch';
+import { isDraftsMode } from '../../lib/config';
 import { getSiteSettings } from '../../lib/shapio';
 import {
   articlesPath,
@@ -73,6 +75,7 @@ const LocaleLayout = async ({ children, params }: LocaleLayoutProps) => {
             {settings?.siteName ?? strings.siteName} · {settings?.footer ?? strings.footer} · Next.js
           </p>
         </footer>
+        {isDraftsMode() ? <DraftsBadge strings={strings} /> : null}
       </body>
     </html>
   );

package/templates/next/src/app/site.css

@@ -197,3 +197,17 @@ main {
   text-align: center;
   font-weight: 600;
 }
+/* Drafts mode (SHAPIO_DRAFTS=true): a corner badge, so a drafts build is never mistaken for the real site. */
+.drafts-badge {
+  position: fixed;
+  right: 1rem;
+  bottom: 1rem;
+  z-index: 10;
+  margin: 0;
+  background: #78350f;
+  color: #fef3c7;
+  padding: 0.25rem 0.75rem;
+  border-radius: 999px;
+  font-size: 0.875rem;
+  font-weight: 700;
+}

package/templates/next/src/components/DraftsBadge/index.tsx

@@ -0,0 +1,10 @@
+import type { Strings } from '../../lib/site';
+
+type DraftsBadgeProps = { strings: Strings };
+
+/** The corner badge of drafts mode (SHAPIO_DRAFTS=true): this server shows saved drafts, not the published site. */
+export const DraftsBadge = ({ strings }: DraftsBadgeProps) => (
+  <p className="drafts-badge" title={strings.draftsNote} data-shapio-drafts="">
+    {strings.drafts}
+  </p>
+);