@jxsuite/studio 6.1.1 → 8.0.0

package/src/content/entry-model.ts

@@ -14,9 +14,9 @@
  *    fill in and "absent" is a validation failure they did not cause.
  * 2. **Where the entry files are** is `collectionInfo`'s answer, imported rather than recomputed.
  *    Three copies of "which collection owns this path, and what extension do its entries carry"
- *    already exist (`utils/studio-utils.ts`'s `findContentTypeSchema`, `grid/sources/content-
- *    source.ts`'s `collectionInfo`, `browse/library-model.ts`'s `contentTypeFor`); this module adds
- *    no fourth and calls the two that are exported.
+ *    existed when this was written (`utils/studio-utils.ts`'s `findContentTypeSchema`,
+ *    `grid/sources/content-source.ts`'s `collectionInfo`, and `browse/library-model.ts`'s
+ *    `contentTypeFor`, since deleted); this module adds no fourth and calls the exported ones.
  *
  * **The draft axis is NOT here.** `content/draft-state.ts` owns what a draft is and whether drafts
  * are listed, because this module imports `content-source.ts` and the grid source must be able to
@@ -27,7 +27,15 @@ import { collectionInfo } from "../grid/sources/content-source";
 import { projectState } from "../store";
 import { findContentTypeSchema } from "../utils/studio-utils";
 import type { ContentSectionEntry } from "../types";
-import type { ContentTypeSchema, ContentTypeSchemaField } from "@jxsuite/schema/types";
+import { isNonNullObject, isString } from "@jxsuite/schema/guards";
+import type {
+  ContentTypeSchema,
+  ContentTypeSchemaField,
+  ContentTypeSchemaValue,
+  JsonObject,
+  JsonValue,
+} from "@jxsuite/schema/types";
+import type { EntryFields } from "./entry-fields";
 
 // ─── Collections ─────────────────────────────────────────────────────────────
 
@@ -44,7 +52,7 @@ export interface EntryCollection {
 
 /** Every content type the project declares, in declaration order. */
 export function collectionNames(): string[] {
-  return Object.keys((projectState?.projectConfig?.content ?? {}) as Record<string, unknown>);
+  return Object.keys(projectState?.projectConfig?.content ?? {});
 }
 
 /**
@@ -91,15 +99,30 @@ export function collectionOfPath(path: string | null): EntryCollection | null {
   return matched ? entryCollection(matched.name) : null;
 }
 
+/**
+ * The collection a file-backed collection's FILE holds the records of (`content/projects.csv`), or
+ * null. {@link entryCollection} refuses one, rightly, for everything that makes a new entry FILE; a
+ * record's form only reads its schema and its name, and `dir` is the file itself.
+ */
+export function recordCollectionOfPath(path: string | null): EntryCollection | null {
+  const matched = findContentTypeSchema(path ?? null, projectState?.projectConfig);
+  const info = matched ? collectionInfo(matched.name) : null;
+  if (!matched || !info) {
+    return null;
+  }
+  return { def: info.def, dir: info.dir, ext: info.ext, name: info.name, schema: matched.schema };
+}
+
 // ─── Seeding a new entry ─────────────────────────────────────────────────────
 
 /** Deep copy of a schema `default`, so two entries seeded from one schema never share an object. */
-function cloneDefault(value: unknown): unknown {
-  if (value === null || typeof value !== "object") {
+function cloneDefault(value: ContentTypeSchemaValue): JsonValue {
+  if (value === null || !isNonNullObject(value)) {
     return value;
   }
+  // SAFETY: `JSON.parse` of what `JSON.stringify` just wrote is JSON by construction.
   // oxlint-disable-next-line unicorn/prefer-structured-clone
-  return JSON.parse(JSON.stringify(value)) as unknown;
+  return JSON.parse(JSON.stringify(value)) as JsonValue;
 }
 
 /**
@@ -109,8 +132,8 @@ function cloneDefault(value: unknown): unknown {
  * and picking an arbitrary entry of the target collection on the author's behalf would be inventing
  * a relationship they never stated.
  */
-function emptyForField(field: ContentTypeSchemaField): unknown {
-  if (typeof field.$ref === "string") {
+function emptyForField(field: ContentTypeSchemaField): JsonValue {
+  if (isString(field.$ref)) {
     return "";
   }
   switch (field.type) {
@@ -125,7 +148,7 @@ function emptyForField(field: ContentTypeSchemaField): unknown {
       return [];
     }
     case "object": {
-      return seedEntry(field as ContentTypeSchema);
+      return seedEntry(field);
     }
     default: {
       return "";
@@ -145,13 +168,13 @@ function emptyForField(field: ContentTypeSchemaField): unknown {
  * author's file full of keys they never asked for, and "the schema mentions it" is not a reason for
  * it to exist on disk — the form still draws a row for it, because the form draws the SCHEMA.
  */
-export function seedEntry(schema: ContentTypeSchema | null | undefined): Record<string, unknown> {
+export function seedEntry(schema: ContentTypeSchema | null | undefined): JsonObject {
   const properties = schema?.properties;
   if (!properties) {
     return {};
   }
-  const required = new Set(Array.isArray(schema?.required) ? schema.required : []);
-  const seed: Record<string, unknown> = {};
+  const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+  const seed: JsonObject = {};
   for (const [name, field] of Object.entries(properties)) {
     if (field.default !== undefined) {
       seed[name] = cloneDefault(field.default);
@@ -168,7 +191,7 @@ export function seedEntry(schema: ContentTypeSchema | null | undefined): Record<
  */
 export function missingRequired(
   schema: ContentTypeSchema | null | undefined,
-  value: Record<string, unknown>,
+  value: EntryFields,
 ): string[] {
   const required = Array.isArray(schema?.required) ? schema.required : [];
   return required.filter((name) => value[name] === undefined);

package/src/content/entry-open.ts

@@ -0,0 +1,80 @@
+/**
+ * Opening a content entry: on the canvas in its writing editor, or in the form when it has no body.
+ *
+ * `specs/studio.md` §22.5: an entry is written on the canvas, inside its template's layout. Opening
+ * one opens the entry's OWN file as an ordinary tab — same id, history and dirty flag as a click in
+ * any file list — in its writing editor (`edit`), which the Content workspace owns (§22.1), so the
+ * Inspector's Entry tab and the writing-mode banner come with it. Every door into an entry goes
+ * through {@link openEntry}: a row in the Content home, an entry in the Collections panel,
+ * `content.openEntry`, and the entry Add new just made.
+ *
+ * The form-only `entry` editor (`content/entry-editor.ts`) stays as the fallback for an entry the
+ * canvas cannot write: a JSON entry IS its fields and has no body, and a file-backed collection's
+ * entries are rows of one file, which open in the grid.
+ *
+ * @docs studio/projects/content-types
+ */
+
+import { activateTab, workspace } from "../workspace/workspace";
+import { collectionForFile } from "./collection-match";
+import { writesEntryOnCanvas } from "./content-collections";
+import { openEntryEditor } from "./entry-editor";
+import type { Tab } from "../tabs/tab";
+
+/** The editor an entry is written in on the canvas. */
+export const WRITING_MODE = "edit";
+
+/** The editors a tab already writes on the canvas in, which an open leaves alone. */
+const CANVAS_MODES: ReadonlySet<string> = new Set(["edit", "design"]);
+
+/**
+ * The open tab for a path, if any (a document tab's id is its path, but a renamed one keeps its
+ * id).
+ */
+function tabFor(path: string): Tab | null {
+  for (const tab of workspace.tabs.values()) {
+    if (tab.documentPath === path) {
+      return tab;
+    }
+  }
+  return null;
+}
+
+/**
+ * Open a content entry where it is written.
+ *
+ * - An entry with a body opens on the canvas in `edit`. A tab already writing it on the canvas
+ *   (`edit` or `design`) keeps its view; a tab showing its form is switched back to writing.
+ * - A JSON entry opens in the form editor.
+ * - Any other file opens as `openFileInTab` would open it.
+ *
+ * @returns The tab, or `null` when the file could not be opened.
+ */
+export async function openEntry(path: string): Promise<Tab | null> {
+  if (!writesEntryOnCanvas(path)) {
+    const match = collectionForFile(path);
+    if (match && !match.fileBacked) {
+      return openEntryEditor(path);
+    }
+    /* Dynamic for the reason `entry-editor.ts` gives: `files/files.ts` reaches the platform, the
+       format registry and the packages layer. */
+    const { openFileInTab } = await import("../files/files");
+    await openFileInTab(path);
+    return tabFor(path);
+  }
+  const { openFileInTab } = await import("../files/files");
+  await openFileInTab(path);
+  const tab = tabFor(path);
+  if (!tab) {
+    return null;
+  }
+  if (
+    !CANVAS_MODES.has(tab.session.ui.canvasMode) &&
+    tab.capabilities.modes.includes(WRITING_MODE)
+  ) {
+    tab.session.ui.canvasMode = WRITING_MODE;
+    tab.session.ui.preview = false;
+  }
+  activateTab(tab.id);
+  return tab;
+}

package/src/content/entry-summaries.ts

@@ -0,0 +1,440 @@
+/**
+ * What the Collections panel says about each entry while one is being written: its title, its
+ * status and a thumbnail (`specs/studio.md` §22.5, the Content-Entry board's list).
+ *
+ * The scan behind the Content home knows each entry's FILE (`browse/library-model.ts`); a title and
+ * a draft flag are inside it. So this reads each entry once — a JSON entry's root, a Markdown
+ * entry's frontmatter, through the same parse the editor uses — and keeps the answer until a file
+ * event drops it ({@link invalidateEntrySummaries}, wired beside the scan's own invalidation in
+ * `studio.ts`). A collection is read when its list is first shown, not before: the panel lists one
+ * collection's entries at a time.
+ *
+ * The read never rejects. An entry that cannot be read is listed under its file name with no
+ * status, which is what the file list would have said about it anyway.
+ *
+ * @docs studio/projects/browse
+ */
+
+import {
+  isBoolean,
+  isJsonObject,
+  isNonNullObject,
+  isNumber,
+  isString,
+} from "@jxsuite/schema/guards";
+import { getPlatform, hasPlatform } from "../platform";
+import { isImage } from "../files/media-upload";
+import { previewFileSrc } from "../files/media-paths";
+import { hasDraftAxis, isDraftEntry } from "./draft-state";
+import { entryCollection } from "./entry-model";
+import { PAGES_COLLECTION, collectionKeyOfPath } from "./content-collections";
+import type { EntryFields } from "./entry-fields";
+import type { ContentTypeSchema, ContentTypeSchemaField } from "@jxsuite/schema/types";
+
+/** One entry, as the Collections panel lists it. */
+export interface EntrySummary {
+  path: string;
+  /** The entry's `title`, or its file name without the extension. */
+  title: string;
+  /** "Draft", "Published", or "" for a collection with no draft workflow. */
+  status: string;
+  /** A preview URL for the entry's first image field, or "" for none. */
+  thumb: string;
+  /** The entry's own date as `YYYY-MM-DD`, from its schema's date field, or "" for none. */
+  date: string;
+  /**
+   * Each field the collection's schema declares and the entry holds, as the text a list cell shows.
+   * Absent from a summary the read did not reach.
+   */
+  fields?: EntryFieldTexts;
+}
+
+/** An entry's declared fields as list text, keyed by field name. */
+export type EntryFieldTexts = Readonly<Record<string, string>>;
+
+/** Field names that mean "what this entry is called", in the order they are preferred. */
+const TITLE_FIELD_NAMES = ["title", "name", "label", "heading"];
+
+/**
+ * The field an entry is called by: `title` where there is one, else the first conventionally named
+ * field (`name`, `label`, `heading`) the schema declares or the entry holds. A menu item with a
+ * `name` and no `title` is "Espresso Tiramisu", not `tiramisu`.
+ */
+export function titleFieldOf(
+  schema: ContentTypeSchema | null | undefined,
+  fields: EntryFields = {},
+): string | null {
+  // Whatever its capitalisation: a CSV's header row is often `Title`, and it is still the title.
+  const named = (keys: readonly string[]): string | null => {
+    for (const wanted of TITLE_FIELD_NAMES) {
+      const key = keys.find((candidate) => candidate.toLowerCase() === wanted);
+      if (key !== undefined) {
+        return key;
+      }
+    }
+    return null;
+  };
+  return (
+    named(Object.keys(schema?.properties ?? {})) ??
+    named(Object.keys(fields).filter((key) => isString(fields[key])))
+  );
+}
+
+/** A field value as list text: a scalar as written, a list of scalars joined, anything else "". */
+export function fieldText(value: EntryFields[string] | Date | undefined): string {
+  if (value instanceof Date) {
+    return entryDay(value);
+  }
+  if (isString(value)) {
+    return value;
+  }
+  if (isNumber(value) || isBoolean(value)) {
+    return String(value);
+  }
+  if (Array.isArray(value)) {
+    return value
+      .filter((item) => isString(item) || isNumber(item))
+      .map(String)
+      .join(", ");
+  }
+  return "";
+}
+
+/** The text of every field the schema declares and the entry holds. */
+function fieldTexts(
+  schema: ContentTypeSchema | null | undefined,
+  fields: EntryFields,
+): EntryFieldTexts {
+  return Object.fromEntries(
+    Object.keys(schema?.properties ?? {})
+      .filter((name) => name in fields)
+      .map((name) => [name, fieldText(fields[name])]),
+  );
+}
+
+/** Field names that mean "when this entry is dated" when the schema types no field as a date. */
+const DATE_FIELD_NAMES = ["date", "published", "publishedAt", "pubDate", "publishDate"];
+
+/**
+ * The field an entry is dated by: the first schema property typed `format: date` or `date-time`,
+ * else the first conventionally named one present in the entry.
+ */
+export function dateFieldOf(
+  schema: ContentTypeSchema | null | undefined,
+  fields: EntryFields,
+): string | null {
+  for (const [name, field] of Object.entries(schema?.properties ?? {})) {
+    if (field.format === "date" || field.format === "date-time") {
+      return name;
+    }
+  }
+  return DATE_FIELD_NAMES.find((name) => name in fields) ?? null;
+}
+
+/**
+ * The field a collection's SCHEMA says its entries are dated by, before any entry is read: the
+ * first property typed `format: date` or `date-time`, else the first conventionally named property
+ * it declares (a `date` with no format is still the date). The Table draws that field in its Date
+ * column, so it is the one field column it must not draw a second time.
+ */
+export function declaredDateField(schema: ContentTypeSchema | null | undefined): string | null {
+  const properties = schema?.properties ?? {};
+  return dateFieldOf(schema, Object.fromEntries(Object.keys(properties).map((name) => [name, ""])));
+}
+
+/**
+ * A date value as `YYYY-MM-DD`, or "". A value that already starts with a calendar date is taken as
+ * written, so a date is never shifted a day by a time zone; anything else must parse.
+ */
+export function entryDay(value: EntryFields[string] | Date): string {
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime()) ? "" : value.toISOString().slice(0, 10);
+  }
+  if (!isString(value)) {
+    return "";
+  }
+  const written = /^(\d{4}-\d{2}-\d{2})/.exec(value.trim());
+  if (written) {
+    return written[1]!;
+  }
+  const parsed = new Date(value);
+  if (value.trim() === "" || Number.isNaN(parsed.getTime())) {
+    return "";
+  }
+  if (!value.includes(":")) {
+    /* A date with no time of day (`6/3/2026`, `March 4, 2026`) parses as LOCAL midnight, so its
+       UTC day is the day before anywhere east of Greenwich: the day is read where it was parsed. */
+    const month = String(parsed.getMonth() + 1).padStart(2, "0");
+    const day = String(parsed.getDate()).padStart(2, "0");
+    return `${parsed.getFullYear()}-${month}-${day}`;
+  }
+  return parsed.toISOString().slice(0, 10);
+}
+
+/** The file name without its extension: `content/posts/hello.md` → `hello`. */
+export function entryStem(path: string): string {
+  const base = path.split("/").pop() ?? path;
+  const dot = base.lastIndexOf(".");
+  return dot > 0 ? base.slice(0, dot) : base;
+}
+
+/**
+ * The project path an image field names, resolved the way the entry's own page resolves it: a
+ * root-relative URL is served from `public/`, anything else is relative to the entry's folder.
+ */
+export function imageFieldPath(entryPath: string, value: string): string {
+  if (value.startsWith("/")) {
+    return `public${value}`;
+  }
+  const dir = entryPath.includes("/") ? entryPath.slice(0, entryPath.lastIndexOf("/")) : "";
+  const parts = [...(dir === "" ? [] : dir.split("/")), ...value.split("/")];
+  const out: string[] = [];
+  for (const part of parts) {
+    if (part === "" || part === ".") {
+      continue;
+    }
+    if (part === "..") {
+      out.pop();
+    } else {
+      out.push(part);
+    }
+  }
+  return out.join("/");
+}
+
+/** A URL with a scheme (`https://…`, `data:…`): a picture somewhere else, shown as it is. */
+const ABSOLUTE_URL = /^[a-z][\d+.a-z-]*:/i;
+
+/** An image field's value as the URL a thumbnail is drawn from, or "" for no picture. */
+function thumbSrc(entryPath: string, value: string): string {
+  const trimmed = value.trim();
+  if (trimmed === "") {
+    return "";
+  }
+  return ABSOLUTE_URL.test(trimmed) ? trimmed : previewFileSrc(imageFieldPath(entryPath, trimmed));
+}
+
+/**
+ * The picture a field holds, when it is one: an image path, an image object's `src`
+ * (`featuredImage: { src, alt }`), or a list of them (its first).
+ */
+function pictureIn(value: EntryFields[string]): string {
+  if (isString(value)) {
+    // A CSV keeps a gallery as one cell, its URLs separated by commas.
+    return value.split(",")[0]?.trim() ?? "";
+  }
+  if (Array.isArray(value)) {
+    const [first] = value;
+    return first === undefined ? "" : pictureIn(first);
+  }
+  if (isJsonObject(value)) {
+    const { src } = value;
+    return isString(src) ? src : "";
+  }
+  return "";
+}
+
+/** Whether a schema property holds a picture: `format: image`, an image object, or a list of either. */
+function isPictureField(field: ContentTypeSchemaField): boolean {
+  if (field.format === "image") {
+    return true;
+  }
+  const src = field.properties?.["src"];
+  if (field.type === "object" && src?.type === "string") {
+    return true;
+  }
+  return field.type === "array" && field.items !== undefined && isPictureField(field.items);
+}
+
+/**
+ * An entry's thumbnail: the first field its SCHEMA declares as a picture that holds one, so a post
+ * is shown by its `cover` and not by whatever image path happens to come first; else the first
+ * field whose value is an image file. A preview URL, or "" for none.
+ */
+export function entryThumb(
+  entryPath: string,
+  fields: EntryFields,
+  schema: ContentTypeSchema | null | undefined,
+): string {
+  for (const [name, field] of Object.entries(schema?.properties ?? {})) {
+    if (isPictureField(field)) {
+      const src = thumbSrc(entryPath, pictureIn(fields[name]));
+      if (src !== "") {
+        return src;
+      }
+    }
+  }
+  for (const value of Object.values(fields)) {
+    if (!isString(value) || ABSOLUTE_URL.test(value)) {
+      continue;
+    }
+    const dot = value.lastIndexOf(".");
+    if (dot > 0 && isImage(value.slice(dot))) {
+      return previewFileSrc(imageFieldPath(entryPath, value));
+    }
+  }
+  return "";
+}
+
+/** One entry's summary, from its fields. Pure. */
+export function summarize(path: string, collection: string, fields: EntryFields): EntrySummary {
+  const schema = entryCollection(collection)?.schema ?? null;
+  const titleField = titleFieldOf(schema, fields);
+  const title = titleField === null ? undefined : fields[titleField];
+  const draft = isDraftEntry(fields);
+  const dateField = dateFieldOf(schema, fields);
+  return {
+    date: dateField === null ? "" : entryDay(fields[dateField]),
+    fields: fieldTexts(schema, fields),
+    path,
+    status: hasDraftAxis(schema, fields) ? (draft ? "Draft" : "Published") : "",
+    thumb: entryThumb(path, fields, schema),
+    title: isString(title) && title.trim() !== "" ? title : entryStem(path),
+  };
+}
+
+/** Read one entry's fields: a JSON entry's root, any other entry's frontmatter. */
+async function readFields(path: string): Promise<EntryFields> {
+  try {
+    const source = await getPlatform().readFile(path);
+    if (path.endsWith(".json")) {
+      const parsed: unknown = JSON.parse(source);
+      /* SAFETY: a JSON entry is an object of fields (its collection's schema says so); a value
+         that is not an object has no fields, which is what the fallback below says. */
+      return isNonNullObject(parsed) && !Array.isArray(parsed) ? (parsed as EntryFields) : {};
+    }
+    const { parseSourceForPath } = await import("../files/file-ops");
+    const parsed = await parseSourceForPath(path, source);
+    return parsed.frontmatter;
+  } catch {
+    return {};
+  }
+}
+
+// ─── The cache ───────────────────────────────────────────────────────────────
+
+/** Entries read, keyed by collection and then by the paths listed, so a changed list re-reads. */
+const _cache = new Map<string, { key: string; entries: EntrySummary[] }>();
+const _loading = new Map<string, Promise<EntrySummary[]>>();
+let _epoch = 0;
+const _listeners = new Set<() => void>();
+
+/** At most this many entries are read for one list; the rest are listed by file name. */
+export const SUMMARY_READ_LIMIT = 200;
+
+/** Read a collection's entries. */
+async function readSummaries(
+  collection: string,
+  paths: readonly string[],
+): Promise<EntrySummary[]> {
+  const read = paths.slice(0, SUMMARY_READ_LIMIT);
+  const summaries = await Promise.all(
+    read.map(async (path) => summarize(path, collection, await readFields(path))),
+  );
+  const rest = paths.slice(SUMMARY_READ_LIMIT).map((path): EntrySummary => ({
+    date: "",
+    path,
+    status: "",
+    thumb: "",
+    title: entryStem(path),
+  }));
+  return [...summaries, ...rest];
+}
+
+/**
+ * A collection's entries as they stand: the summaries, or `null` while they are being read (which
+ * starts the read; listeners are told when it lands).
+ *
+ * @param collection - The collection's name.
+ * @param paths - Its entry files, in the order to list them.
+ */
+export function peekEntrySummaries(
+  collection: string,
+  paths: readonly string[],
+): EntrySummary[] | null {
+  const key = paths.join("\n");
+  const cached = _cache.get(collection);
+  if (cached?.key === key) {
+    return cached.entries;
+  }
+  if (!hasPlatform()) {
+    return paths.map((path) => ({ date: "", path, status: "", thumb: "", title: entryStem(path) }));
+  }
+  const inFlight = `${collection}\n${key}`;
+  if (!_loading.has(inFlight)) {
+    const epoch = _epoch;
+    const read: Promise<EntrySummary[]> = readSummaries(collection, paths).then((entries) => {
+      /* Only this read's own record: an invalidation in between may have handed the key to a newer
+         read, and deleting THAT record would let the next peek start a duplicate of it. */
+      if (_loading.get(inFlight) === read) {
+        _loading.delete(inFlight);
+      }
+      if (epoch === _epoch) {
+        _cache.set(collection, { entries, key });
+        for (const listener of _listeners) {
+          listener();
+        }
+      }
+      return entries;
+    });
+    _loading.set(inFlight, read);
+  }
+  return null;
+}
+
+/**
+ * Restate one entry from the fields Studio just saved, without reading the file back.
+ *
+ * A save is Studio's own write, so the fields it wrote are the answer, and re-reading them is both
+ * slower and wrong: the dev server lets a file read be cached for five seconds, and its watcher
+ * skips some trees outright, so the list kept the old title after an author renamed an entry and
+ * pressed Save. An entry no cached list holds is left to that list's own first read.
+ *
+ * @returns Whether a cached list held the entry and now states the saved fields.
+ */
+export function noteEntrySaved(path: string, collection: string, fields: EntryFields): boolean {
+  const cached = _cache.get(collection);
+  const index = cached?.entries.findIndex((entry) => entry.path === path) ?? -1;
+  if (!cached || index === -1) {
+    return false;
+  }
+  const entries = cached.entries.with(index, summarize(path, collection, fields));
+  _cache.set(collection, { entries, key: cached.key });
+  for (const listener of _listeners) {
+    listener();
+  }
+  return true;
+}
+
+/**
+ * After a document saved: restate its entry, when it is one, from the fields it saved.
+ *
+ * The caller says where the fields live (`entryFields(tab)`, the live record, not a copy), which
+ * keeps the editor's field store out of this data module's graph.
+ *
+ * @param path The saved document's path, or `null` for one with no file.
+ * @param fields The saved document's fields: a JSON entry's root, any other entry's frontmatter.
+ * @returns Whether a cached list changed, so the caller knows a repaint is due.
+ */
+export function noteSavedEntry(path: string | null, fields: EntryFields): boolean {
+  const collection = collectionKeyOfPath(path);
+  if (path === null || collection === null || collection === PAGES_COLLECTION) {
+    return false;
+  }
+  return noteEntrySaved(path, collection, fields);
+}
+
+/** Forget every summary. The next list re-reads its entries. */
+export function invalidateEntrySummaries(): void {
+  _epoch += 1;
+  _cache.clear();
+  _loading.clear();
+}
+
+/** Be told when a read lands. Returns the function that stops it. */
+export function onEntrySummariesRead(listener: () => void): () => void {
+  _listeners.add(listener);
+  return () => {
+    _listeners.delete(listener);
+  };
+}