@jxsuite/studio 6.1.2 → 8.0.1

package/src/content/collection-pages.ts

@@ -0,0 +1,412 @@
+/**
+ * Which page each collection's entries are published at — read from the pages, never stored.
+ *
+ * `project.json` records no URL pattern and no template for a collection. The route lives in the
+ * template PAGE: a dynamic file under `pages/` whose `$paths.contentType` names the collection
+ * (`pages/blog/[slug].json`, `$paths: { contentType: "posts", param: "slug" }`), or whose
+ * `$paths.values` enumerate the ids of a `ContentEntry` it reads by its route parameter (a taxonomy
+ * page, `pages/author/[slug].json`), and the layout an entry is drawn in is that page's `$layout`.
+ * A second record of either in `project.json` would be free to disagree with the router, so the
+ * Content workspace's header line ("Each post has a page at `/blog/:slug` using Post") and the
+ * canvas's entry wrapping (`canvas/canvas-live-render.ts`) both read this index (`specs/studio.md`
+ * §22.5).
+ *
+ * One read per invalidation: a walk of `pages/`, then a parse of each dynamic page, cached until a
+ * file event drops it ({@link invalidateCollectionPages}, wired beside the Site panel's index in
+ * `studio.ts`). The read never rejects; a page that cannot be read or parsed is a page with no
+ * collection.
+ *
+ * @docs studio/projects/browse
+ */
+
+import { isJsonObject, isNumber, isString } from "@jxsuite/schema/guards";
+import { fileToRoute, isRoutedPageFile } from "@jxsuite/site/routes";
+import {
+  canonicalizeLocale,
+  localeOfPath,
+  resolveI18n,
+  servedLocaleOfPath,
+} from "@jxsuite/schema/locale";
+import { getPlatform, hasPlatform } from "../platform";
+import { projectState } from "../store";
+import { pagePathsDef } from "../page-params";
+import type { FormatFrontmatter } from "../format/format-host";
+import type { JxDocumentValue, JxMutableNode } from "@jxsuite/schema/types";
+import type { EntryFields } from "./entry-fields";
+import type { DirEntry } from "../types";
+
+/** What a page under `pages/` says about collections and layouts. */
+export interface PageFacts {
+  /** The collection its `$paths` expands over, or `null` for a page of its own. */
+  contentType: string | null;
+  /** The route parameter an entry fills (`slug`), when `$paths` names one. */
+  param: string | null;
+  /** The entry field that fills it (`sku`), when `$paths` names one other than `id`. */
+  field: string | null;
+  /** Its `$layout`: a path, `false` (no layout), or `undefined` (the project's default). */
+  layout: string | false | undefined;
+  /**
+   * The ids a `$paths.values` page enumerates (`["chad-beiler", "kris-bucher"]`): the only entries
+   * it publishes a URL for. `null` for a `$paths.contentType` page, which publishes every entry,
+   * and for a `values` that is not a list of ids written in the page.
+   */
+  values?: readonly string[] | null;
+}
+
+/** A collection's template page. */
+export interface CollectionPage {
+  /** The page file, project-relative (`pages/blog/[slug].json`). */
+  path: string;
+  /** Its URL pattern (`/blog/:slug`). */
+  pattern: string;
+  /** The parameter an entry's id fills, or `null` when the page names none. */
+  param: string | null;
+  /** The entry field the parameter is read from, as {@link PageFacts.field}. */
+  field: string | null;
+  /** The page's `$layout`, as {@link PageFacts.layout}. */
+  layout: string | false | undefined;
+  /** The only entry ids it publishes, as {@link PageFacts.values}; null or absent for every one. */
+  values?: readonly string[] | null;
+  /**
+   * The language the page is served in (`pages/ar/exhibitions/[slug].json` → `ar`), or `null` in a
+   * project without `i18n` and for a page outside every locale tree.
+   */
+  locale: string | null;
+}
+
+/**
+ * The collection a page enumerating its own `$paths.values` publishes one entry of per URL: the
+ * `contentType` of its `ContentEntry` state entry whose `id` is the route parameter (`{ "$ref":
+ * "#/$params/slug" }`). A taxonomy page (`pages/author/[slug].json`, listing the author slugs and
+ * reading `state.author` from the `author` collection by that slug) states its collection that way
+ * rather than with `$paths.contentType`, and is the collection's page all the same.
+ */
+function entryCollectionOf(
+  document: JxMutableNode | null,
+  frontmatter: FormatFrontmatter | null,
+  param: string,
+): string | null {
+  const state = document?.state ?? frontmatter?.state;
+  const target = `#/$params/${param}`;
+  for (const entry of Object.values(isJsonObject(state) ? state : {})) {
+    if (!isJsonObject(entry) || entry.$prototype !== "ContentEntry") {
+      continue;
+    }
+    const { contentType, id } = entry;
+    if (isJsonObject(id) && id.$ref === target && isString(contentType) && contentType !== "") {
+      return contentType;
+    }
+  }
+  return null;
+}
+
+/** The facts a page document states, from its parsed tree and (for a format page) frontmatter. */
+export function pageFactsOf(
+  document: JxMutableNode | null,
+  frontmatter: FormatFrontmatter | null,
+): PageFacts {
+  const paths = pagePathsDef({ document, frontmatter });
+  let contentType: string | null = null;
+  let param: string | null = null;
+  let field: string | null = null;
+  let values: string[] | null = null;
+  if (paths && !Array.isArray(paths) && "contentType" in paths) {
+    const type = paths.contentType;
+    contentType = isString(type) && type !== "" ? type : null;
+    const named = "param" in paths ? paths.param : undefined;
+    param = isString(named) && named !== "" ? named : null;
+    const from = "field" in paths ? paths.field : undefined;
+    field = isString(from) && from !== "" && from !== "id" ? from : null;
+  } else if (paths && !Array.isArray(paths) && "values" in paths) {
+    const named = "param" in paths ? paths.param : undefined;
+    const enumerated = isString(named) && named !== "" ? named : null;
+    contentType = enumerated === null ? null : entryCollectionOf(document, frontmatter, enumerated);
+    param = contentType === null ? null : enumerated;
+    // The ids it lists are the entries it publishes; any other entry of the collection has no page.
+    const listed = paths.values;
+    values =
+      contentType !== null && Array.isArray(listed)
+        ? listed.flatMap((value) => {
+            const id = segmentOf(value);
+            return id === null ? [] : [id];
+          })
+        : null;
+  }
+  const own = document?.$layout ?? frontmatter?.$layout;
+  const layout = isString(own) || own === false ? own : undefined;
+  return { contentType, field, layout, param, ...(values !== null && { values }) };
+}
+
+/**
+ * Read one page's facts from disk. A file that cannot be read or parsed states none.
+ *
+ * @param path - Project-relative page path.
+ */
+export async function readPageFacts(path: string): Promise<PageFacts> {
+  const none: PageFacts = { contentType: null, field: null, layout: undefined, param: null };
+  try {
+    const source = await getPlatform().readFile(path);
+    if (path.endsWith(".json")) {
+      /* SAFETY: a `.json` file under `pages/` is a page document by the project layout; a file
+         that does not parse throws into the catch below, which is "no facts". */
+      return pageFactsOf(JSON.parse(source) as JxMutableNode, null);
+    }
+    const { parseSourceForPath } = await import("../files/file-ops");
+    const parsed = await parseSourceForPath(path, source);
+    /* SAFETY: a format class's parser returns its file as a Jx element tree (the format
+       contract); `pageFactsOf` reads `$paths` and `$layout` off it and nothing else. */
+    return pageFactsOf(parsed.document as JxMutableNode, parsed.frontmatter);
+  } catch {
+    return none;
+  }
+}
+
+// ─── The index ───────────────────────────────────────────────────────────────
+
+/** Every template page of each collection, in path order. A multilingual site has one per language. */
+type CollectionPageIndex = Map<string, CollectionPage[]>;
+
+let _index: CollectionPageIndex | null = null;
+let _loading: Promise<CollectionPageIndex> | null = null;
+/** Bumped by every invalidation, so a read that started before one cannot land after it. */
+let _epoch = 0;
+/** Told when a read lands, so a surface showing a stale answer can repaint. */
+const _listeners = new Set<() => void>();
+
+/** Every file under `pages/`, recursively. An unreadable directory contributes nothing. */
+async function listPages(dir: string, out: string[]): Promise<void> {
+  let entries: DirEntry[];
+  try {
+    entries = await getPlatform().listDirectory(dir);
+  } catch {
+    return;
+  }
+  await Promise.all(
+    entries.map(async (entry) => {
+      if (entry.type === "directory") {
+        await listPages(entry.path, out);
+      } else {
+        out.push(entry.path);
+      }
+    }),
+  );
+}
+
+/** One walk of `pages/`, then the facts of every dynamic page in it. */
+async function readIndex(): Promise<CollectionPageIndex> {
+  const files: string[] = [];
+  await listPages("pages", files);
+  /* Only routed pages: an underscore-prefixed file or folder is private to its directory and
+     publishes nothing, and it would otherwise win the path-order tie below (`_` sorts first). */
+  const dynamic = files.filter((path) => path.includes("[") && isRoutedPageFile(path)).toSorted();
+  const facts = await Promise.all(
+    dynamic.map(async (path) => [path, await readPageFacts(path)] as const),
+  );
+  const { i18n } = resolveI18n(projectState?.projectConfig ?? {});
+  const index: CollectionPageIndex = new Map();
+  for (const [path, fact] of facts) {
+    if (fact.contentType) {
+      const page: CollectionPage = {
+        field: fact.field,
+        layout: fact.layout,
+        locale: servedLocaleOfPath(path, i18n),
+        param: fact.param,
+        path,
+        pattern: fileToRoute(path).urlPattern,
+        ...(fact.values && { values: fact.values }),
+      };
+      index.set(fact.contentType, [...(index.get(fact.contentType) ?? []), page]);
+    }
+  }
+  return index;
+}
+
+/**
+ * The index, read once per invalidation.
+ *
+ * With no platform or no project there is nothing to read, and the answer is an empty map rather
+ * than a rejection.
+ */
+export function collectionPages(): Promise<CollectionPageIndex> {
+  if (_index) {
+    return Promise.resolve(_index);
+  }
+  if (!hasPlatform() || !projectState) {
+    return Promise.resolve(new Map());
+  }
+  if (!_loading) {
+    const epoch = _epoch;
+    _loading = readIndex().then((index) => {
+      if (epoch === _epoch) {
+        _index = index;
+        _loading = null;
+        for (const listener of _listeners) {
+          listener();
+        }
+      }
+      return index;
+    });
+  }
+  return _loading;
+}
+
+/**
+ * The one of a collection's template pages that serves `locale`.
+ *
+ * A multilingual site gives a collection one template page per language
+ * (`pages/exhibitions/[slug].json`, `pages/ar/exhibitions/[slug].json`, …), and "the" page is the
+ * one in the language asked about: an Arabic entry is drawn in the Arabic page's layout, and the
+ * header for the English view names the English URL. With no language asked, or none of the pages
+ * in it, the answer is the site's default language's page, then a page outside every locale tree,
+ * then the first in path order, so two pages over one collection still answer deterministically.
+ */
+export function pageForLocale(
+  pages: readonly CollectionPage[] | undefined,
+  locale: string | null | undefined,
+): CollectionPage | null {
+  if (!pages || pages.length === 0) {
+    return null;
+  }
+  const wanted = canonicalizeLocale(locale);
+  const fallback = resolveI18n(projectState?.projectConfig ?? {}).i18n?.defaultLocale ?? null;
+  return (
+    (wanted === null ? undefined : pages.find((page) => page.locale === wanted)) ??
+    (fallback === null ? undefined : pages.find((page) => page.locale === fallback)) ??
+    pages.find((page) => page.locale === null) ??
+    pages[0]!
+  );
+}
+
+/** The language a collection entry is written in, read from its path (`content/x/ar/a.md` → `ar`). */
+export function entryLocale(path: string | null | undefined): string | null {
+  if (!path) {
+    return null;
+  }
+  return localeOfPath(path, resolveI18n(projectState?.projectConfig ?? {}).i18n);
+}
+
+/**
+ * A collection's template page as the index stands: the page, `null` when the collection has none,
+ * or `undefined` while the index has not been read yet (which starts the read).
+ *
+ * @param locale - The language asked about, as {@link pageForLocale} reads it.
+ */
+export function peekCollectionPage(
+  name: string,
+  locale?: string | null,
+): CollectionPage | null | undefined {
+  if (!_index) {
+    void collectionPages();
+    return undefined;
+  }
+  return pageForLocale(_index.get(name), locale);
+}
+
+/**
+ * Every template page of a collection, one per language in a multilingual site, as the index
+ * stands: `[]` for none, `undefined` while the index has not been read (which starts the read).
+ */
+export function peekCollectionPages(name: string): readonly CollectionPage[] | undefined {
+  if (!_index) {
+    void collectionPages();
+    return undefined;
+  }
+  return _index.get(name) ?? [];
+}
+
+/** A collection's template page for a language, reading the index if it has to. */
+export async function collectionPage(
+  name: string,
+  locale?: string | null,
+): Promise<CollectionPage | null> {
+  const index = await collectionPages();
+  return pageForLocale(index.get(name), locale);
+}
+
+/** Forget the index. The next read walks `pages/` again. */
+export function invalidateCollectionPages(): void {
+  _epoch += 1;
+  _index = null;
+  _loading = null;
+}
+
+/** Be told when a read of the index lands. Returns the function that stops it. */
+export function onCollectionPagesRead(listener: () => void): () => void {
+  _listeners.add(listener);
+  return () => {
+    _listeners.delete(listener);
+  };
+}
+
+/** A field value as a route segment: text or a number, else nothing. */
+function segmentOf(value: JxDocumentValue | undefined): string | null {
+  if (isString(value) && value !== "") {
+    return value;
+  }
+  return isNumber(value) && Number.isFinite(value) ? String(value) : null;
+}
+
+/**
+ * The URL one entry opens at, from its collection's page pattern, filled as the build fills it
+ * (`Content.resolvePaths`): the page's `$paths.field` read from the entry's fields when it names
+ * one (`/products/:sku` with the entry's `sku`), else the entry's id (a JSON entry's `id` field,
+ * else its file stem). `null` when the collection has no page, or when its page enumerates the ids
+ * it publishes (`$paths.values`) and this entry is not among them.
+ *
+ * @param fields - The entry's fields (frontmatter, or a JSON entry's root), when the caller has
+ *   them.
+ */
+export function entryUrl(
+  page: CollectionPage | null,
+  entryPath: string,
+  fields?: Readonly<EntryFields> | null,
+): string | null {
+  if (!page) {
+    return null;
+  }
+  const base = entryPath.split("/").pop() ?? entryPath;
+  const dot = base.lastIndexOf(".");
+  const stem = dot > 0 ? base.slice(0, dot) : base;
+  const own = page.field === null ? null : segmentOf(fields?.[page.field]);
+  // Only a JSON entry's own `id` names it (the loader's `jsonEntry`); a Markdown entry is its file.
+  const named = entryPath.endsWith(".json") ? segmentOf(fields?.id) : null;
+  const id = own ?? named ?? stem;
+  // A page that lists the ids it publishes has no URL for an entry it does not list.
+  if (page.values && !page.values.includes(id)) {
+    return null;
+  }
+  if (page.param) {
+    return page.pattern.replace(`:${page.param}`, id);
+  }
+  return page.pattern.replace(/:[A-Za-z_]\w*/, id);
+}
+
+/**
+ * The layout an entry is drawn in (§22.5): its own `$layout`, else its collection's template page's
+ * `$layout`, else the project's `defaults.layout`. `null` when none applies, or when the first of
+ * them to speak says `false`.
+ */
+export function entryLayoutPath(
+  own: string | false | undefined,
+  page: CollectionPage | null,
+): string | null {
+  if (own === false) {
+    return null;
+  }
+  if (isString(own) && own !== "") {
+    return own;
+  }
+  if (page?.layout === false) {
+    return null;
+  }
+  if (isString(page?.layout) && page.layout !== "") {
+    return page.layout;
+  }
+  return projectState?.projectConfig?.defaults?.layout ?? null;
+}
+
+/** Forget everything — tests, and a project switch. */
+export function resetCollectionPages(): void {
+  invalidateCollectionPages();
+  _listeners.clear();
+}

package/src/content/content-collections.ts

@@ -0,0 +1,270 @@
+/**
+ * The collections the Content workspace lists: a built-in **Pages** collection, then every
+ * collection `project.json` declares, in declaration order (`specs/studio.md` §9.1.2, §22.5).
+ *
+ * One answer to "which collection is this file in", and it is `content/collection-match.ts`'s. A
+ * routed file under `pages/` is a page; any other file is in the collection `collectionForFile`
+ * names, or in none. The Library this replaces had a third matcher (`contentTypeFor`, a source
+ * prefix test) and folder categories beside it, and the two disagreed about the same entry; both
+ * are gone, and nothing here guesses from a folder name.
+ *
+ * Pure over the open project's configuration: no DOM, no platform, so the commands that name a
+ * collection can build their `enum` in a bare Bun process.
+ *
+ * @docs studio/projects/browse
+ */
+
+import { isRoutedPageFile } from "@jxsuite/site/routes";
+import { projectState } from "../store";
+import { MEDIA_EXTENSIONS, extensionOf } from "../files/media-types";
+import { collectionForFile } from "./collection-match";
+import type { ContentSectionEntry } from "../types";
+import type { ContentTypeSchema } from "@jxsuite/schema/types";
+
+/**
+ * Collection names whose singular is the word itself. The suffix rules below would make `news` a
+ * `new`, `series` a `sery` and `species` a `specy`, and the result is visible copy ("New new").
+ */
+const INVARIANT_NOUNS = new Set(["data", "media", "metadata", "news", "series", "species"]);
+
+/**
+ * Collections named for the WHOLE rather than its parts: a `menu` holds dishes, a `gallery`
+ * pictures. Their item is "<name> item", the noun English already uses ("menu item", "catalog
+ * item"); "New menu" would promise a second menu.
+ */
+const COLLECTIVE_NOUNS = new Set([
+  "archive",
+  "catalog",
+  "catalogue",
+  "collection",
+  "directory",
+  "faq",
+  "gallery",
+  "inventory",
+  "library",
+  "menu",
+  "portfolio",
+  "showcase",
+]);
+
+/**
+ * A storage name in words, as a person reads it: `project_tag` → "project tag", `service-type` →
+ * "service type", `docsNav` → "docs nav". Lower case; {@link capitalise} makes a heading of it.
+ */
+export function humanName(name: string): string {
+  return name
+    .replaceAll(/[_-]+/g, " ")
+    .replaceAll(/([a-z\d])([A-Z])/g, "$1 $2")
+    .trim()
+    .replaceAll(/\s+/g, " ")
+    .toLowerCase();
+}
+
+/** A collection's item, said in the singular: `recipes` → `recipe`, `stories` → `story`. */
+export function itemNoun(collection: string): string {
+  // Only the last word is a noun to singularise: `post_tags` is a "post tag".
+  // A one-word name keeps its own spelling (`News`); a compound one is said in lower-case words.
+  const words = /[_-]|[a-z\d][A-Z]/.test(collection) ? humanName(collection) : collection;
+  const at = words.lastIndexOf(" ");
+  const last = words.slice(at + 1);
+  if (COLLECTIVE_NOUNS.has(last.toLowerCase())) {
+    return `${words} item`;
+  }
+  return `${words.slice(0, at + 1)}${singular(last)}`;
+}
+
+/** One word in the singular. */
+function singular(collection: string): string {
+  if (INVARIANT_NOUNS.has(collection.toLowerCase())) {
+    return collection;
+  }
+  if (/[^aeiou]ies$/.test(collection)) {
+    return `${collection.slice(0, -3)}y`;
+  }
+  // `classes` → `class`, `boxes` → `box`, `matches` → `match`: the plural added `es`.
+  if (/(?:ss|x|ch|sh|z)es$/.test(collection)) {
+    return collection.slice(0, -2);
+  }
+  // `status`, `campus`, `analysis`, `glass` are already singular.
+  if (/(?:us|is|ss)$/.test(collection)) {
+    return collection;
+  }
+  if (collection.endsWith("s")) {
+    return collection.slice(0, -1);
+  }
+  return collection;
+}
+
+/** A word with its first letter in capitals: `posts` → `Posts`. */
+export function capitalise(word: string): string {
+  return word.charAt(0).toUpperCase() + word.slice(1);
+}
+
+/**
+ * A template or page file's display name, from its file name: `./layouts/post.json` → `Post`,
+ * `./layouts/blog-post.json` → `Blog Post`. The one spelling every surface that names a template
+ * uses, so the header line, the writing banner and the layout picker never disagree.
+ */
+export function templateDisplayName(path: string): string {
+  const base = path.replaceAll("\\", "/").split("/").pop() ?? path;
+  return base
+    .replace(/\.[^.]+$/, "")
+    .replaceAll(/[-_]+/g, " ")
+    .replaceAll(/\b\w/g, (c: string) => c.toUpperCase());
+}
+
+/** The key of the built-in collection every site has: the routed files under `pages/`. */
+export const PAGES_COLLECTION = "pages";
+
+/** One collection, as the Content workspace names it. */
+export interface ContentCollection {
+  /** `pages`, or the collection's name in `project.json`. The value every command names. */
+  key: string;
+  /** What the heading says: "Pages", or the collection's name capitalised. */
+  title: string;
+  /** One of its items, in the singular and lower case: "page", "post", "story". */
+  item: string;
+  /** `pages` for the built-in collection, `collection` for a declared one. */
+  kind: "pages" | "collection";
+  /** True for a collection whose `source` is one file (a CSV catalogue): its entries are rows. */
+  fileBacked: boolean;
+}
+
+/** The declared collections, name → entry, in declaration order. */
+function contentSection(): Record<string, ContentSectionEntry> {
+  /* SAFETY: `content` is the parser extension's section, collection name → entry object; this
+     module reads only the optional `source`, and only to ask whether it names one file. */
+  return (projectState?.projectConfig?.content ?? {}) as Record<string, ContentSectionEntry>;
+}
+
+/** Whether a `source` names a single file rather than a directory. */
+function namesFile(source: string | undefined): boolean {
+  return source !== undefined && /\.[\da-z]+$/i.test(source.replace(/\/+$/, ""));
+}
+
+/** The built-in Pages collection. */
+const PAGES: ContentCollection = {
+  fileBacked: false,
+  item: "page",
+  key: PAGES_COLLECTION,
+  kind: "pages",
+  title: "Pages",
+};
+
+/** Every collection the Content workspace lists: Pages first, then the declared ones. */
+export function contentCollections(): ContentCollection[] {
+  const declared = Object.entries(contentSection()).map(([name, def]): ContentCollection => ({
+    fileBacked: namesFile(def.source),
+    item: itemNoun(name),
+    key: name,
+    kind: "collection",
+    // In words, as the Table names a field: `project_tag` is "Project tag", not "Project_tag".
+    title: capitalise(humanName(name)),
+  }));
+  return [PAGES, ...declared];
+}
+
+/** Every collection key, for a command's `enum`: `pages` first, then the declared names. */
+export function contentCollectionKeys(): string[] {
+  return contentCollections().map((collection) => collection.key);
+}
+
+/**
+ * The project-relative file a file-backed collection's entries are rows of (`./content/p.csv` →
+ * `content/p.csv`), or `null` for a collection whose source is a directory, or none at all.
+ */
+export function collectionSourceFile(key: string): string | null {
+  const source = contentSection()[key]?.source;
+  return source !== undefined && namesFile(source) ? source.replace(/^\.\//, "") : null;
+}
+
+/** The schema a collection declares, file-backed or not, or `null` for none. */
+export function declaredCollectionSchema(key: string): ContentTypeSchema | null {
+  return contentSection()[key]?.schema ?? null;
+}
+
+/** The collection with this key, or `null` when the project declares none by that name. */
+export function contentCollection(key: string): ContentCollection | null {
+  return contentCollections().find((collection) => collection.key === key) ?? null;
+}
+
+/**
+ * The collection a file is in, or `null`.
+ *
+ * Media files are in none: an image beside an entry is the entry's asset, which the Media workspace
+ * lists. A file under `pages/` is a page; any other is `collectionForFile`'s answer.
+ */
+export function collectionKeyOfPath(path: string | null | undefined): string | null {
+  if (!path) {
+    return null;
+  }
+  const normalized = path.replaceAll("\\", "/").replace(/^\.\//, "");
+  if (MEDIA_EXTENSIONS.has(extensionOf(normalized))) {
+    return null;
+  }
+  if (normalized.startsWith("pages/")) {
+    // An underscore-prefixed file or folder is a page directory's private part, not a route.
+    return isRoutedPageFile(normalized) ? PAGES_COLLECTION : null;
+  }
+  return collectionForFile(normalized)?.name ?? null;
+}
+
+/**
+ * Whether an entry is written on the canvas rather than in the form editor.
+ *
+ * An entry with a body (a Markdown file, or any format with prose) is written on the canvas inside
+ * its template's layout (§22.5). A JSON entry IS its fields, with no body to write, and a
+ * file-backed collection's entries are rows: both keep the form-only `entry` editor.
+ */
+export function writesEntryOnCanvas(path: string | null | undefined): boolean {
+  if (!path) {
+    return false;
+  }
+  const match = collectionForFile(path);
+  if (!match || match.fileBacked) {
+    return false;
+  }
+  const ext = extensionOf(path);
+  return ext !== ".json" && ext !== ".csv";
+}
+
+/** Which of the Content workspace's three derived caches a batch of file events can make wrong. */
+export interface ContentCacheDrops {
+  /** The scan the collections are filtered from: only the file SET, so adds, removes and renames. */
+  scan: boolean;
+  /** The pages that say where each collection is published: any write under `pages/`. */
+  pages: boolean;
+  /** The titles and statuses the Collections panel lists: any write to a collection's entry. */
+  entries: boolean;
+}
+
+/**
+ * Which Content caches a file-event batch drops.
+ *
+ * A plain content `change` cannot change which files exist, so it leaves the scan alone; that is
+ * every save, Studio's own echoes included, and dropping the scan on each one blanked the
+ * Collections panel and re-walked the project after every keystroke-and-save. It can still change a
+ * template page's `$paths` (the index) and an entry's title or status (the summaries), so those are
+ * dropped by path.
+ *
+ * @param paths The project-relative paths the batch touched, or `undefined` after a gap, when any
+ *   path may have changed.
+ * @param structural Whether the batch added, removed or renamed anything.
+ */
+export function contentCacheDrops(
+  paths: readonly string[] | undefined,
+  structural: boolean,
+): ContentCacheDrops {
+  if (paths === undefined || structural) {
+    return { entries: true, pages: true, scan: true };
+  }
+  const normalized = paths.map((path) => path.replaceAll("\\", "/").replace(/^\.\//, ""));
+  return {
+    entries: normalized.some((path) => {
+      const key = collectionKeyOfPath(path);
+      return key !== null && key !== PAGES_COLLECTION;
+    }),
+    pages: normalized.some((path) => path.startsWith("pages/")),
+    scan: false,
+  };
+}