@jtakeit/astro 0.1.0

package/template/src/lib/entryLoader.ts

@@ -0,0 +1,315 @@
+import type { Loader, LoaderContext } from 'astro/loaders';
+import { createSatteriMarkdownProcessor } from '@astrojs/markdown-satteri';
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { HAST_PLUGINS } from '../../markdown.mjs';
+import { BLOCKS, type Collection } from '../content/blocks';
+// The one place that says what a specimen is called. The meta plugin needs the
+// same answer — an address nobody can find is a draft the edge hands to
+// anybody — and a rule written twice is a rule that ends up meaning two things.
+import { specimenId } from '../../specimens.mjs';
+
+/**
+ * Reading a collection's entries out of the repository.
+ *
+ * ── why this is a loader of ours and not `glob` ─────────────────────────────
+ *
+ * An entry used to be markdown with frontmatter, and Astro's glob loader read
+ * exactly that shape with nothing of ours in between. It could hold one block,
+ * because the body *was* the file — and a post that wants a gallery between two
+ * paragraphs cannot be written that way at all (the platform's wiki/30).
+ *
+ * So an entry is a document of blocks now, like every other page: a `.json`
+ * file with `blocks`, the first of which is the post — its title, its date, its
+ * cover and its prose. Everything after it is whatever the collection lets a
+ * post hold, rendered by this site's own components.
+ *
+ * Which leaves one job glob cannot do: the prose is a *string* now, and it has
+ * to become HTML through the same markdown pipeline as everything else.
+ *
+ * ── and not through `ctx.renderMarkdown`, which is the trap ────────────────
+ *
+ * That is the sanctioned call and it builds its renderer **without the plugins
+ * this site configured** — Astro's own code, not a setting: it passes `image`,
+ * `syntaxHighlight`, `shikiConfig`, `gfm` and `smartypants`, and stops. A body
+ * rendered through it silently loses `figures.mjs`, so a row of three
+ * photographs comes out as three paragraphs. Measured, not guessed at: the
+ * markers Astro leaves for its image pipeline were still in the HTML.
+ *
+ * So the same renderer is built here with the same options, from
+ * `markdown.mjs`, which is the one place either this or `astro.config.mjs`
+ * reads. The `fileURL` is what makes `![](one.jpg)` resolve **beside the
+ * entry's own file** — which is exactly where the build downloads it, so the
+ * media pipeline is untouched by any of this — and `imagePaths` is what Astro
+ * reads back to optimise them.
+ */
+export function entries(collection: Collection): Loader {
+  return {
+    name: 'jtakeit-entries',
+    async load(ctx: LoaderContext) {
+      const base = join(process.cwd(), 'jtk', 'content', collection.prefix.replace(/^\//, ''));
+      // No `image:` here on purpose. The processor's image option is
+      // `{ domains, remotePatterns }` — which remote pictures may be fetched —
+      // and not the site's `{ layout }`. Passing the latter type-checked as
+      // nothing in common and meant nothing at runtime; the layout is applied
+      // when Astro replaces the markers, from the site config.
+      const renderer = await createSatteriMarkdownProcessor({ hastPlugins: HAST_PLUGINS });
+      ctx.store.clear();
+      /** Whatever this collection's own entries show, for the specimens below. */
+      const seen: string[] = [];
+
+      for (const file of await jsonUnder(base)) {
+        const raw = await readFile(file, 'utf8');
+        const document = JSON.parse(raw) as {
+          blocks?: Record<string, unknown>[];
+          visible?: boolean;
+          seo?: Record<string, unknown>;
+        };
+        const blocks = document.blocks ?? [];
+
+        // blocks[0] is the post. A document with none is not corrupt — it is an
+        // entry somebody emptied — and refusing to load it would take the only
+        // page from which it can be seen and fixed.
+        const post = blocks[0] ?? {};
+        const body = typeof post.body === 'string' ? post.body : '';
+
+        const id = relative(base, file).split(sep).join('/').replace(/\.json$/, '');
+        const rendered = await drawn(renderer, body, pathToFileURL(file));
+
+        ctx.store.set({
+          id,
+          data: {
+            ...post,
+            /** Everything after the post, for the template to render. */
+            rest: await written(renderer, blocks.slice(1), file),
+            /** Whether the site lists it. The page itself is always built. */
+            visible: document.visible !== false,
+            /*
+             * What the post is found by, where it is not what it is called.
+             *
+             * The admin writes these two beside the post — a title for a result
+             * list and the sentence under it — and they are an override, not a
+             * requirement: a post that says nothing here is found by its own
+             * heading and its announcement. Read in `[...entry].astro`, which
+             * is the only place that knows what a head tag is.
+             */
+            seo: document.seo ?? {},
+          },
+          rendered,
+          /*
+           * The half that is easy to leave out and impossible to notice.
+           *
+           * `imagePaths` in the rendered metadata is what the *runtime* reads
+           * to swap a marker for an optimised picture. This is what makes the
+           * pictures exist to swap in: the store builds `content-assets` from
+           * `assetImports` and from nothing else. Without it the build passes,
+           * the page renders, and every picture in a post is an `<img>` with a
+           * marker where its `src` should be — which is exactly what happened
+           * the first time, and the reason there is a test for it.
+           */
+          assetImports: rendered.metadata.imagePaths,
+          digest: ctx.generateDigest(raw),
+          filePath: relative(process.cwd(), file),
+        });
+
+        for (const found of pictures(blocks)) seen.push(found);
+      }
+
+      await specimens(ctx, renderer, collection, seen);
+    },
+  };
+}
+
+/**
+ * One page per arrangement, built with everything else and listed nowhere.
+ *
+ * ── why a site builds a page nobody will read ───────────────────────────────
+ *
+ * The admin's preview is the built site with the draft patched onto it, and
+ * that works while the shape is the shape the build knows. Put a gallery into a
+ * post and it stops: the page has no element for it, and only a build can make
+ * one — the arrangement is this repository's markup and this repository's CSS,
+ * and an admin that drew its own would be guessing at both.
+ *
+ * So the build draws one of each, once. The admin takes the markup from here
+ * and puts it where the new block goes, and what somebody sees is this site's
+ * own arrangement rather than an approximation of it.
+ *
+ * ── rendered by the route that renders the real thing ───────────────────────
+ *
+ * Not by a page of its own. A fragment rendered somewhere else is styled
+ * somewhere else — `:nth-child`, the classes of a parent, a grid that counts
+ * its children — and the copy would be subtly wrong in a way nobody could see
+ * until it was live. These are entries, so they go through `[...entry].astro`
+ * inside the same article as every other post, and the context is identical by
+ * construction.
+ *
+ * ── invisible, and that is not a trick ──────────────────────────────────────
+ *
+ * `visible: false` is the same flag a post nobody has finished carries: every
+ * place that *lists* entries skips it, the sitemap never sees it, and the
+ * studio's edge serves it only to a session that is editing the site. Which is
+ * exactly who asks for it.
+ *
+ * The pictures are the site's own, taken from the entries it already has. A
+ * collection with no photographs anywhere gets an empty arrangement — the
+ * container without its contents, which is still the right container.
+ */
+async function specimens(
+  ctx: LoaderContext,
+  renderer: Renderer,
+  collection: Collection,
+  pictures: string[],
+): Promise<void> {
+  for (const kind of collection.body ?? []) {
+    const type = BLOCKS.find((one) => one.type === kind);
+    if (type === undefined) continue;
+
+    for (const view of type.views ?? [undefined]) {
+      const block: Record<string, unknown> = { _key: `${kind}-1`, type: kind, v: type.v };
+      if (view !== undefined) block.view = view.key;
+
+      const gallery = type.fields.find((one) => one.kind === 'media' && one.multiple === true);
+      if (gallery !== undefined) {
+        const wanted = Math.max(1, view?.min ?? 1);
+        block[gallery.key] = pictures.slice(0, wanted).map((src) => ({ src, alt: '' }));
+      }
+      for (const field of type.fields) {
+        if (field.kind === 'text' && block[field.key] === undefined) block[field.key] = ' ';
+        if (field.kind === 'markdown' && block[field.key] === undefined) block[field.key] = ' ';
+      }
+
+      ctx.store.set({
+        id: specimenId(kind, view?.key),
+        data: {
+          title: ' ',
+          rest: await written(renderer, [block], 'specimen'),
+          visible: false,
+          seo: {},
+        },
+        rendered: { html: '', metadata: {} },
+        digest: ctx.generateDigest(JSON.stringify(block)),
+      });
+    }
+  }
+}
+
+/** Every picture a document points at, in the order it points at them. */
+function* pictures(blocks: Record<string, unknown>[]): Generator<string> {
+  for (const block of blocks) {
+    for (const value of Object.values(block)) {
+      if (!Array.isArray(value)) continue;
+      for (const item of value) {
+        const src = (item as Record<string, unknown> | null)?.src;
+        if (typeof src === 'string' && src !== '') yield src;
+      }
+    }
+  }
+}
+
+/**
+ * The blocks after the post, with every run of prose in them turned to HTML.
+ *
+ * A post is a sequence — prose, a gallery, more prose — and the runs after the
+ * first are `text` blocks. They are rendered here rather than by Astro's own
+ * `render()`, which does one body per entry and knows nothing about a second.
+ *
+ * Prose only: a picture in a post is a block chosen from the menu this
+ * repository declares, not an `![]()` written into the text. The build says so
+ * rather than rendering a broken image, because the failure is otherwise a
+ * marker in the HTML that nobody sees until the page is live.
+ */
+async function written(
+  renderer: Renderer,
+  blocks: Record<string, unknown>[],
+  file: string,
+): Promise<Record<string, unknown>[]> {
+  const out: Record<string, unknown>[] = [];
+
+  for (const block of blocks) {
+    if (block.type !== 'text') {
+      out.push(block);
+      continue;
+    }
+
+    const body = typeof block.body === 'string' ? block.body : '';
+    if (/!\[[^\]]*\]\(/.test(body)) {
+      throw new Error(
+        `${file}: a run of text in a post may not hold a picture — a picture is a block. ` +
+          'See COLLECTIONS[].body and the block menu in the admin.',
+      );
+    }
+
+    const { code } = await renderer.render(body, { frontmatter: {}, fileURL: pathToFileURL(file) });
+    out.push({ ...block, html: code });
+  }
+
+  return out;
+}
+
+/**
+ * The prose as HTML, in the shape the content store expects.
+ *
+ * `imagePaths` is the half that is easy to leave out and impossible to notice:
+ * it is how Astro knows which files to optimise, and without it the markers it
+ * left in the HTML are never replaced — a picture in a post renders as an
+ * `<img>` with no `src` at all.
+ */
+async function drawn(renderer: Renderer, body: string, fileURL: URL) {
+  const { code, metadata } = await renderer.render(body, { frontmatter: {}, fileURL });
+
+  return {
+    html: code,
+    metadata: {
+      ...metadata,
+      imagePaths: [...(metadata.localImagePaths ?? []), ...(metadata.remoteImagePaths ?? [])],
+    },
+  };
+}
+
+/**
+ * The renderer, taken from the function that makes one rather than described
+ * again here.
+ *
+ * It used to be a hand-written signature, and the copy drifted: it said
+ * `metadata` was `Record<string, string[] | undefined>`, while the real one is
+ * `{ headings, localImagePaths, remoteImagePaths, frontmatter }` — `headings`
+ * is not an array of strings and `frontmatter` is not an array at all. Four
+ * errors, and the sort that gets worse rather than better, because the
+ * description was in this file and the thing described is in a package that
+ * keeps moving.
+ *
+ * Deriving it leaves nothing to drift. It is deliberately NOT
+ * `import type { MarkdownRenderer } from '@astrojs/internal-helpers/markdown'`:
+ * that package is not a dependency of this project, only a transitive one of
+ * astro, and reaching across that line is a build that breaks on somebody
+ * else's refactor.
+ */
+type Renderer = Awaited<ReturnType<typeof createSatteriMarkdownProcessor>>;
+
+/** Every `.json` under a collection, however deeply a site nests them. */
+async function jsonUnder(dir: string): Promise<string[]> {
+  let found: string[] = [];
+
+  let listing;
+  try {
+    listing = await readdir(dir, { withFileTypes: true });
+  } catch {
+    // A collection nobody has written an entry for yet. Not an error: a site
+    // ships its blog before its first post.
+    return [];
+  }
+
+  for (const item of listing) {
+    const full = join(dir, item.name);
+    // A collection's own pictures land beside its entries at build time. They
+    // are not entries, and reading one as such is a stack trace.
+    if (item.isDirectory()) {
+      if (item.name !== 'media') found = found.concat(await jsonUnder(full));
+      continue;
+    }
+    if (item.name.endsWith('.json')) found.push(full);
+  }
+  return found;
+}

package/template/src/lib/noise.ts

@@ -0,0 +1,26 @@
+/**
+ * One noise tile, for everything in the kit that needs grain.
+ *
+ * Two places wanted it — the `grain` ground in components/surface/patterns.ts
+ * and the `film` treatment on a photograph — and two copies of a texture is how
+ * one of them gets retuned and the other does not. It lives here because
+ * src/lib is never pruned from a handoff, so neither caller has to own it.
+ *
+ * Turbulence makes the noise; the colour matrix throws the colour away and
+ * keeps the red channel as *alpha*, which is what a CSS mask reads.
+ * `stitchTiles` is what lets it repeat without a seam.
+ */
+export const GRAIN_TILE =
+  "url(\"data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='180' height='180'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.86' numOctaves='4' stitchTiles='stitch'/%3E%3CfeColorMatrix type='matrix' values='0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 0 0'/%3E%3C/filter%3E%3Crect width='180' height='180' filter='url(%23n)'/%3E%3C/svg%3E\")";
+
+/**
+ * How big the tile is drawn.
+ *
+ * `GRAIN_SIZE` is what it was authored at, and it is right for a ground: a
+ * page-sized layer needs a tile large enough that the repeat is never obvious.
+ * A photograph is a few hundred pixels wide, so the same tile covers half of it
+ * and the noise reads as blotches and streaks rather than as grain — the smaller
+ * value scales it down into something the eye takes for film.
+ */
+export const GRAIN_SIZE = '180px';
+export const GRAIN_SIZE_PHOTO = '90px';

package/template/src/lib/page.ts

@@ -0,0 +1,287 @@
+import type { Shown } from '../copy/{{LOCALE}}';
+import { LOCALES } from '../content/blocks';
+
+/**
+ * Any page's content document, for a site that has more than one.
+ *
+ * ── what a second page costs, and why it is this file ───────────────────────
+ *
+ * The home page reads its own document through `src/copy/<locale>.ts`, which is
+ * that page's *vocabulary*: `HOME.hero.title`, `HOME.cta.label`, shaped by hand
+ * to the blocks this site happens to have. It is rewritten per project, which
+ * is exactly why the generic reader is not in it — an agent reshaping the home
+ * page's copy must not be able to break how every other page is read.
+ *
+ * So: a second page imports this, names its own path, and gets the same three
+ * things the home page has — the blocks in order, a way to reach one, and the
+ * annotation path for every field it renders.
+ *
+ *   ---
+ *   import { readPage } from '../lib/page';
+ *   const prices = readPage('/prices');
+ *   const { at, of } = prices.block('rates');
+ *   ---
+ *   <h2 data-jtk-path={prices.pathAt(at, 'title')}>{prices.str(of, 'title')}</h2>
+ *
+ * ── the document has to be in the repository ────────────────────────────────
+ *
+ * `jtk/content/prices.json` is committed with empty strings in it, the
+ * same way `index.json` is, and for the same reason: a static import of a file
+ * that is not there is a build error rather than an empty page, and a fresh
+ * project has to build on a laptop before it has ever been attached.
+ *
+ * The admin learns the page exists when the branch is imported — a page is a
+ * file somebody wrote, and that is the only way one comes into being.
+ */
+
+type Block = Record<string, unknown> & { type: string };
+type Item = Record<string, unknown>;
+
+interface Document {
+  path?: string;
+  seo?: Record<string, unknown>;
+  /** The page's language. Absent is the site's own — see the platform's wiki/29. */
+  locale?: string;
+  blocks?: Block[];
+}
+
+/** One language of a page, for `hreflang` and for a switcher. */
+export interface Alternate {
+  /** Empty is the site's own language. `META.lang` is what it is called. */
+  locale: string;
+  path: string;
+}
+
+/**
+ * Every page document in the repository, keyed by the path it declares.
+ *
+ * Eager, because a page is read while its route renders and there is nothing to
+ * wait for; and by glob rather than by import, because the whole point is that
+ * a route names a path and does not have to know which file it lives in.
+ */
+const documents = import.meta.glob<Document>('/jtk/content/**/*.json', {
+  eager: true,
+  import: 'default',
+});
+
+/**
+ * The shared document, if this site has one.
+ *
+ * A glob of exactly one file rather than an import of it, because a static
+ * import of a file that is not there is a build error — and most sites have
+ * none. `readShared()` on a site without one answers with nothing, and every
+ * `str` off it is an empty string, which is what a page renders before anything
+ * has been written.
+ */
+const sharedDocuments: Record<string, Document | undefined> = {};
+for (const [file, document] of Object.entries(
+  import.meta.glob<Document>('/jtk/shared*.json', { eager: true, import: 'default' }),
+)) {
+  // shared.json is the site's own language; shared.de.json is German. Named
+  // rather than nested, because there is one per language and a directory of
+  // one file is a directory somebody has to explain.
+  const match = /\/shared(?:\.([a-z]{2}(?:-[a-z]{2})?))?\.json$/.exec(file);
+  if (match !== null) sharedDocuments[match[1] ?? ''] = document;
+}
+
+const ANNOTATE = import.meta.env.PUBLIC_JTK_ANNOTATE !== 'false';
+
+export interface Reading {
+  /** The page's language, empty for the site's own. */
+  locale: string;
+  /**
+   * Every language this page exists in, itself included, in the order the
+   * documents were found.
+   *
+   * Empty for a page that has one language, which is most pages on most sites.
+   * **Feed it to `<Layout alternates={…}>`**: without `hreflang` two language
+   * versions of one page compete with each other in search, which is the only
+   * thing in this whole area that costs money.
+   */
+  alternates: Alternate[];
+  /** The page's own title and description, for `<Layout>`. */
+  seo: { title: string; description: string };
+  /** Every block, in the document's own order. */
+  PAGE: readonly Block[];
+  /** A block by type, with the index an annotation path is built from. */
+  block(type: string): { at: number; of: Block };
+  str(of: Block, key: string): string;
+  rows(of: Block, key: string): Item[];
+  picture(of: Block, at: number, key: string): Shown;
+  gallery(of: Block, at: number, key: string): Shown[];
+  pathAt(at: number, field: string, item?: number, subField?: string): string | undefined;
+}
+
+export function readPage(path: string): Reading {
+  return reading(find(path), '');
+}
+
+/**
+ * Another page's document, read from the page that is *showing* it.
+ *
+ * ── a tile in a list is somebody else's words ───────────────────────────────
+ *
+ * A blog listing draws a heading, a date and an excerpt for every post, and
+ * every one of them belongs to that post's document rather than to the
+ * listing's. Annotated the ordinary way they would name a field the listing
+ * page has not got, so until this existed they carried no annotation at all —
+ * and the words an owner most wants to fix were the one place on their site
+ * they could not tap.
+ *
+ * The prefix says which document, by the address the tile already links to:
+ *
+ *   <a data-jtk-path={post.pathAt(0, 'title')}>{post.str(of, 'title')}</a>
+ *   →  data-jtk-path="page:/blog/healing:blocks[0].title"
+ *
+ * The admin resolves it against that page, writes it there, and the post's own
+ * page updates with it. `annotation-lint` checks the claim from the other end:
+ * an address no page has, or a field that page's document has not got, fails
+ * the build.
+ *
+ * Use it where a page renders another page's content and nowhere else. A
+ * heading you wrote in *this* page's document is this page's, however much it
+ * looks like a tile.
+ */
+export function readOther(path: string): Reading {
+  return reading(find(path), `page:${path}:`);
+}
+
+/**
+ * The text that is on every page.
+ *
+ * ── one value, and the annotation says which document it is in ──────────────
+ *
+ * A footer sentence, the line under the wordmark, the words over the form. They
+ * are on every page and belong to none of them, and the wrong answer is the
+ * obvious one: declared in each page's document, a three-page site has three
+ * copies, and they diverge the first time somebody edits one. The owner changes
+ * the footer on the prices page, looks at the home page, and reports that their
+ * change disappeared. It did not — it was saved, on one page in three.
+ *
+ * So it lives in `jtk/shared.json`, once, and every field of it is
+ * annotated with the prefix that says so:
+ *
+ *   <p data-jtk-path={chrome.pathAt(at, 'note')}>{chrome.str(of, 'note')}</p>
+ *   →  data-jtk-path="shared:blocks[0].note"
+ *
+ * `pathAt` here writes the prefix for you. **Annotate it on every page that
+ * renders it** — unlike a page's own field, the same annotation on five pages
+ * is correct and is what makes the sentence editable wherever somebody happens
+ * to be looking. The admin resolves it against the site's document, not the
+ * page's, and tells the owner the line is on every page before they change it.
+ */
+export function readShared(locale = ''): Reading {
+  return reading(sharedDocuments[locale], 'shared:');
+}
+
+/**
+ * The languages a page exists in.
+ *
+ * ── from the address, because the address is the whole rule ─────────────────
+ *
+ * A page lives at the same address in every language, with the language in
+ * front of it: `/prices` and `/de/preise` are not a pair, `/prices` and
+ * `/de/prices` are. So take the language off the front and look for the same
+ * address under every other one.
+ *
+ * This used to read a `group` key both documents declared, which let each
+ * language have its own words. That key is a second source of truth for
+ * something the addresses already say, and one nobody can check: `group:
+ * "work"` on one page against `group: "works"` on the other is two unrelated
+ * pages, no error anywhere, and a site that has quietly lost its hreflang. The
+ * platform stopped reading it and `fl-check` refuses a document that still
+ * carries one.
+ *
+ * A page in one language answers with nothing rather than with itself: a
+ * `hreflang` set of one is noise.
+ */
+function alternatesOf(document: Document | undefined): Alternate[] {
+  const here = document?.path;
+  if (typeof here !== 'string') return [];
+
+  const base = basePathOf(here);
+  const found = Object.values(documents)
+    .filter((other) => typeof other?.path === 'string' && basePathOf(other.path as string) === base)
+    .map((other) => ({ locale: other?.locale ?? '', path: other?.path as string }));
+
+  return found.length > 1 ? found : [];
+}
+
+/** `/de/prices` → `/prices`, and `/de` → `/`, which is the home page. */
+function basePathOf(path: string): string {
+  for (const locale of LOCALES) {
+    if (path === `/${locale}` || path === `/${locale}/`) return '/';
+    if (path.startsWith(`/${locale}/`)) return path.slice(locale.length + 1);
+  }
+  return path;
+}
+
+function reading(document: Document | undefined, prefix: string): Reading {
+  const blocks = (document?.blocks ?? []) as Block[];
+
+  const str = (of: Block, key: string): string => (of[key] as string) ?? '';
+  const rows = (of: Block, key: string): Item[] => (of[key] as Item[]) ?? [];
+
+  const pathAt = (at: number, field: string, item?: number, subField?: string): string | undefined => {
+    if (!ANNOTATE) return undefined;
+    if (at < 0 || at >= blocks.length) return undefined;
+
+    return item === undefined
+      ? `${prefix}blocks[${at}].${field}`
+      : `${prefix}blocks[${at}].${field}[${item}].${subField}`;
+  };
+
+  const block = (type: string): { at: number; of: Block } => {
+    const at = blocks.findIndex((candidate) => candidate.type === type);
+    // A block the document does not have is not an error: the admin can remove
+    // one, and a page that threw at build time because a section was deleted
+    // would make removing a section a deploy incident.
+    return at === -1 ? { at: -1, of: { type } } : { at, of: blocks[at]! };
+  };
+
+  return {
+    locale: document?.locale ?? '',
+    alternates: alternatesOf(document),
+    seo: {
+      title: (document?.seo?.title as string) ?? '',
+      description: (document?.seo?.description as string) ?? '',
+    },
+    PAGE: blocks,
+    block,
+    str,
+    rows,
+    pathAt,
+    picture: (of, at, key) => ({
+      name: str(of, key),
+      alt: str(of, `${key}_alt`),
+      path: pathAt(at, key),
+    }),
+    gallery: (of, at, key) =>
+      rows(of, key).flatMap((item, i) => {
+        const src = (item.src as string) ?? '';
+        if (!src) return [];
+        return [
+          {
+            name: src,
+            alt: (item.alt as string) ?? '',
+            poster: (item.poster as string) || undefined,
+            path: pathAt(at, key, i, 'src'),
+          },
+        ];
+      }),
+  };
+}
+
+/**
+ * The document that declares this path.
+ *
+ * By the `path` inside the file rather than by the file's name, because that is
+ * what publish writes and what the admin reads back: the two must agree about
+ * which page is which, and a file somebody renamed is a page that moved.
+ */
+function find(path: string): Document | undefined {
+  for (const document of Object.values(documents)) {
+    if (document?.path === path) return document;
+  }
+  return undefined;
+}