@jxsuite/studio 6.1.1 → 8.0.0

package/src/commands/run-reported.ts

@@ -55,7 +55,8 @@
 import { errorMessage } from "@jxsuite/schema/parse";
 import { notify } from "../services/notify";
 import { activeRegistry } from "./active-registry";
-import type { CommandArgs, CommandRegistry } from "./registry";
+import type { CommandArgValues } from "./command-args";
+import type { CommandRegistry } from "./registry";
 
 /**
  * Whether an error is one of the two REFUSAL shapes, whose message is written to be read whole.
@@ -64,10 +65,10 @@ import type { CommandArgs, CommandRegistry } from "./registry";
  * `handleKeyEvent`, and a value import back would close a cycle for one class whose constructor
  * sets exactly this name. `RangeError` is the shape `coerceArgs` and a `run` body refuse with.
  */
-function isRefusal(error: unknown): boolean {
+function isRefusal(cause: unknown): boolean {
   return (
-    error instanceof RangeError ||
-    (error instanceof Error && error.name === "CommandUnavailableError")
+    cause instanceof RangeError ||
+    (cause instanceof Error && cause.name === "CommandUnavailableError")
   );
 }
 
@@ -86,15 +87,15 @@ function isRefusal(error: unknown): boolean {
 export function runReported(
   registry: CommandRegistry,
   id: string,
-  args?: CommandArgs,
+  args?: CommandArgValues,
   source: string = id,
 ): Promise<void> {
-  const report = (error: unknown) => {
-    if (!isRefusal(error)) {
+  const report = (cause: unknown) => {
+    if (!isRefusal(cause)) {
       // A crash, not a refusal: the row below carries the sentence, the console keeps the stack.
-      console.error(`${source}: command "${id}" failed`, error);
+      console.error(`${source}: command "${id}" failed`, cause);
     }
-    notify.error(errorMessage(error), { key: `command.run:${id}`, source });
+    notify.error(errorMessage(cause), { key: `command.run:${id}`, source });
   };
   let result: void | Promise<void>;
   try {
@@ -114,7 +115,11 @@ export function runReported(
  * registry to refuse it, so there is no refusal to file. The resolved promise keeps the caller's
  * `void` honest either way.
  */
-export function runActiveReported(id: string, args?: CommandArgs, source?: string): Promise<void> {
+export function runActiveReported(
+  id: string,
+  args?: CommandArgValues,
+  source?: string,
+): Promise<void> {
   const registry = activeRegistry();
   return registry ? runReported(registry, id, args, source) : Promise.resolve();
 }

package/src/component-props.ts

@@ -11,8 +11,13 @@
  */
 
 import type { JsonValue } from "./types";
-import type { JxMutableNode } from "@jxsuite/schema/types";
-import { isPrivateStateKey } from "@jxsuite/schema/guards";
+import type {
+  JsonPrimitive,
+  JxMutableNode,
+  JxStateDefinition,
+  JxStateObject,
+} from "@jxsuite/schema/types";
+import { isNonNullObject, isPrivateStateKey, isString } from "@jxsuite/schema/guards";
 
 /** One editable prop row: the state key and its current default value (undefined = none). */
 export interface ComponentPropEntry {
@@ -22,7 +27,16 @@ export interface ComponentPropEntry {
 
 /** Whether the doc is a component definition (a custom-element root) rather than a page. */
 export function isComponentDoc(doc: JxMutableNode | null | undefined): boolean {
-  return typeof doc?.tagName === "string" && doc.tagName.includes("-");
+  const tagName = doc?.tagName;
+  return isString(tagName) && tagName.includes("-");
+}
+
+/** The object shapes a state entry can take: every `JxStateDefinition` but a primitive or array. */
+type StateEntryObject = Exclude<JxStateDefinition, JsonPrimitive | JsonValue[]>;
+
+/** Whether a state entry is one of its object shapes — a signal, a typed def, a naked object. */
+function isStateEntryObject(def: JxStateDefinition | undefined): def is StateEntryObject {
+  return isNonNullObject(def) && !Array.isArray(def);
 }
 
 /**
@@ -31,26 +45,20 @@ export function isComponentDoc(doc: JxMutableNode | null | undefined): boolean {
  * templates, or $prototype data sources (overriding those would clobber behavior, the boundPropKey
  * rule).
  */
-function propShape(def: unknown): "literal" | "signal" | null {
-  if (def === null || typeof def === "number" || typeof def === "boolean") {
-    return "literal";
-  }
-  if (typeof def === "string") {
-    return def.includes("${") ? null : "literal"; // Template strings render computed values.
-  }
-  if (Array.isArray(def)) {
-    return "literal";
+function propKind(def: JxStateDefinition | undefined): "literal" | "signal" | null {
+  if (def === undefined) {
+    return null;
   }
-  if (typeof def === "object") {
-    const d = def as Record<string, unknown>;
-    if (d.$expression || d.$compute || d.$prototype || d.$handler) {
+  if (isStateEntryObject(def)) {
+    if (def.$expression || def.$compute || def.$prototype || def.$handler) {
       return null;
     }
     // An expanded signal ({default}) or a typed prop def ({type}/schema keywords) seeds through
     // Its `default`; any other plain object is a Shape-1 naked value.
-    return "default" in d || "type" in d ? "signal" : "literal";
+    return "default" in def || "type" in def ? "signal" : "literal";
   }
-  return null;
+  // Null, numbers, booleans and arrays are naked literals. Template strings render computed values.
+  return isString(def) && def.includes("${") ? null : "literal";
 }
 
 /**
@@ -58,20 +66,20 @@ function propShape(def: unknown): "literal" | "signal" | null {
  * entries with their current default values (the CEM-export "field" subset).
  */
 export function componentPropEntries(doc: JxMutableNode | null | undefined): ComponentPropEntry[] {
-  const state = (doc?.state ?? {}) as Record<string, unknown>;
+  const state: Record<string, JxStateDefinition> = doc?.state ?? {};
   const out: ComponentPropEntry[] = [];
   for (const [name, def] of Object.entries(state)) {
     if (isPrivateStateKey(name)) {
       continue; // Private entries are not props (spec.md §5.6).
     }
-    const shape = propShape(def);
-    if (!shape) {
+    const kind = propKind(def);
+    if (!kind) {
       continue;
     }
-    const value =
-      shape === "signal"
-        ? ((def as { default?: JsonValue }).default as JsonValue | undefined)
-        : (def as JsonValue);
+    /* SAFETY: `propKind` refused every behavioral shape (expressions, computeds, `$prototype`
+       sources, handlers, template strings), so what is left is the document's plain data: a
+       literal entry IS the JSON value, and a signal entry is an object whose `default` is one. */
+    const value = kind === "signal" ? (def as { default?: JsonValue }).default : (def as JsonValue);
     out.push({ name, value });
   }
   return out;
@@ -87,19 +95,27 @@ export function substitutePreviewProps(
   renderDoc: JxMutableNode,
   props: Record<string, JsonValue>,
 ): JxMutableNode {
-  const state = { ...((renderDoc.state ?? {}) as Record<string, unknown>) };
+  const state = { ...renderDoc.state };
   let seeded = false;
   for (const [name, value] of Object.entries(props)) {
-    const shape = propShape(state[name]);
-    if (!shape) {
+    const current = state[name];
+    const kind = propKind(current);
+    if (!kind) {
       continue; // Unknown/behavioral entries are never overridden by a stale test value.
     }
-    state[name] =
-      shape === "signal" ? { ...(state[name] as Record<string, unknown>), default: value } : value;
+    /* SAFETY: `propKind` answers "signal" only for an object that carries `default` or `type` and
+       none of the behavioral keys (`$expression`, `$compute`, `$prototype`, `$handler`) — the
+       expanded-signal / typed-def shape `JxStateObject` describes. A literal is replaced by the
+       JSON test value itself, which is a Shape-1 naked entry; `JxStateDefinition` spells that
+       shape as `JxStateObject`, whose typed keys neither a `JsonObject` nor a spread copy can prove
+       statically (the spread drops the index signature its typed keys are checked against). */
+    state[name] = (
+      kind === "signal" ? { ...(current as JxStateObject), default: value } : value
+    ) as JxStateDefinition;
     seeded = true;
   }
   if (!seeded) {
     return renderDoc;
   }
-  return { ...renderDoc, state } as JxMutableNode;
+  return { ...renderDoc, state };
 }

package/src/content/collection-match.ts

@@ -1,12 +1,13 @@
 /**
  * Collection-match — the ONE answer to "which content collection owns this path".
  *
- * Three matchers already existed and disagreed: `utils/studio-utils.ts`'s `findContentTypeSchema`,
+ * Three matchers existed and disagreed: `utils/studio-utils.ts`'s `findContentTypeSchema`,
  * `grid/sources/content-source.ts`'s `collectionInfo` and `browse/library-model.ts`'s
- * `contentTypeFor`. Each was right about the question it was written for and wrong about the
- * others', which was tolerable while the consumers were a form and a grid. It stopped being
- * tolerable when the Files tree began asking, because a mismatch there does not draw the wrong
- * field — it CONSTRAINS or REROUTES a creation, and both are wrong answers the author cannot see.
+ * `contentTypeFor` (since deleted: the Content workspace asks this module instead). Each was right
+ * about the question it was written for and wrong about the others', which was tolerable while the
+ * consumers were a form and a grid. It stopped being tolerable when the Files tree began asking,
+ * because a mismatch there does not draw the wrong field — it CONSTRAINS or REROUTES a creation,
+ * and both are wrong answers the author cannot see.
  *
  * Four things this states that no predecessor did:
  *
@@ -32,12 +33,10 @@
 import { defaultContentFormat, formatByName } from "../format/format-host";
 import { projectState } from "../store";
 import { resolveI18n } from "@jxsuite/schema/locale";
+import { LOCALE_PLACEHOLDER } from "../canvas/asset-resolve";
 import type { ContentSectionEntry } from "../types";
 import type { ProjectConfig } from "@jxsuite/schema/types";
 
-/** The placeholder a localized `source` carries, standing for one directory per declared locale. */
-export const LOCALE_PLACEHOLDER = "{locale}";
-
 /** What a path's collection is, and everything a caller needs in order to act on it. */
 export interface CollectionMatch {
   name: string;
@@ -69,11 +68,14 @@ function normalize(path: string): string {
 
 /** The config a lookup reads: the caller's, or the open project's. */
 function configOf(config: ProjectConfig | null | undefined): ProjectConfig | null {
-  return config ?? (projectState?.projectConfig as ProjectConfig | null | undefined) ?? null;
+  return config ?? projectState?.projectConfig ?? null;
 }
 
 /** The `content` section of a config, or an empty one. */
 function contentSection(config: ProjectConfig | null): Record<string, ContentSectionEntry> {
+  /* SAFETY: `content` is the parser extension's section — collection name → entry object, its
+     project fragment schema the source of truth. `ContentSectionEntry` names only the fields Studio
+     reads, every one optional, and each reader below tests `source` before using it. */
   return (config?.content ?? {}) as Record<string, ContentSectionEntry>;
 }
 

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