@jxsuite/studio 6.1.1 → 8.0.0

package/src/browse/library-preview.ts

@@ -22,18 +22,28 @@
 import {
   buildScope,
   renderNode,
+  runScoped,
   setCanvasAssetResolver,
+  setNpmModuleResolver,
+  setResolveToken,
   setSkipServerFunctions,
+  setTemplateErrorHandler,
 } from "@jxsuite/runtime";
+import { isFunction, isNonNullObject } from "@jxsuite/schema/guards";
 import { assetContextFor, hostAssetDeclarations, resolveAssetRef } from "../canvas/asset-refs";
+import { canvasBaseOrigin, documentBase, hostResolveToken } from "../canvas/canvas-origin";
+import { npmModuleUrl } from "../canvas/npm-modules";
+import { projectState } from "../store";
 import { assetVersionsSnapshot } from "../files/asset-versions";
 import { componentRegistry } from "../files/components";
 import { getPlatform } from "../platform";
 import { loadFormats, formatForPath } from "../format/format-host";
 import { parseSourceForPath } from "../files/file-ops";
-import { renderComponentPreview } from "../panels/component-preview";
+import { defineComponent, renderComponentPreview } from "../panels/component-preview";
+import { componentExampleProps, componentSampleRow } from "./component-examples";
+import { loadProjectPreviewSheets } from "./preview-style";
 import type { ComponentEntry } from "../files/components";
-import type { JxDocument } from "@jxsuite/schema/types";
+import type { JsonValue, JxDocument } from "@jxsuite/schema/types";
 
 /**
  * How many rendered previews stay alive at once.
@@ -74,12 +84,13 @@ export function createPreviewCache(limit: number = PREVIEW_CACHE_LIMIT): Preview
   const entries = new Map<string, HTMLElement>();
 
   function evict() {
-    // `size > limit` guarantees a first key, so the iterator result is never `done` here.
-    while (entries.size > limit) {
-      const oldest = entries.keys().next().value as string;
-      const stale = entries.get(oldest);
+    // Insertion order is LRU order, and deleting the entry being visited is safe mid-iteration.
+    for (const [oldest, stale] of entries) {
+      if (entries.size <= limit) {
+        break;
+      }
       entries.delete(oldest);
-      stale?.remove();
+      stale.remove();
     }
   }
 
@@ -111,6 +122,16 @@ export function createPreviewCache(limit: number = PREVIEW_CACHE_LIMIT): Preview
 
 // ─── Rendering one preview ───────────────────────────────────────────────────
 
+/**
+ * The URL a previewed document's relative refs resolve against: the file's own URL under the
+ * project, as the canvas spells it. A shell with an opaque origin (a custom-scheme shell such as
+ * `views://`) has no such URL to build, and keeps the shell's own address.
+ */
+function previewBase(filePath: string): string {
+  const base = documentBase(projectState?.projectRoot);
+  return URL.canParse(base) ? new URL(filePath, base).href : location.href;
+}
+
 /**
  * Render a page/layout/content document to a detached element, or null when it cannot be rendered.
  *
@@ -127,30 +148,137 @@ export async function renderDocPreview(filePath: string): Promise<HTMLElement |
     let document_: JxDocument;
     if (formatForPath(filePath)) {
       const parsed = await parseSourceForPath(filePath, content);
+      /* SAFETY: a format class's parser returns its file as a Jx element tree (the format contract),
+         and the split hands that same tree back as `document`; a tree renderNode cannot draw throws
+         into the catch below, which is "no preview". */
       document_ = parsed.document as JxDocument;
     } else {
+      /* SAFETY: a `.json` file in the Library is a project document by the project layout; malformed
+         JSON or a shape renderNode cannot draw throws into the catch below, which is "no preview". */
       document_ = JSON.parse(content) as JxDocument;
     }
-    const scope = await buildScope(document_, {}, location.href);
-    /* This render lands in the PARENT document, so an `<img src="/hero.jpg">` inside it resolves
-       against `index.html` — which is the shell, not the site. Same hook the canvas installs, same
-       context, restored afterwards because the next preview is a different document and a stale
-       `documentDir` would resolve its relative refs against the wrong entry. The version map is
-       read as the render starts, after the reads above: the Library is the many-images screen,
-       and a versioned src is what lets its cards repaint from the browser cache. */
-    const assets = context && { ...context, versions: assetVersionsSnapshot() };
-    setCanvasAssetResolver((value) => resolveAssetRef(value, assets));
-    try {
-      const element = renderNode(document_, scope);
-      return element instanceof HTMLElement ? element : null;
-    } finally {
-      setCanvasAssetResolver(null);
-    }
+    return await renderDocument(document_, filePath, context);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Render a document as the file `filePath` holds it would be drawn: its refs resolved from that
+ * file's URL, its media through the canvas's resolver. Throws what the render throws.
+ */
+async function renderDocument(
+  document_: JxDocument,
+  filePath: string,
+  context = assetContextFor(filePath, hostAssetDeclarations()),
+): Promise<HTMLElement | null> {
+  setSkipServerFunctions(true);
+  /* The document's own URL, as the canvas spells it, and the canvas's dev-proxy token. With the
+     shell's `location.href` as base, a page's `"$src": "../../scripts/x.class.json"` resolved
+     against `/__studio__/`, and without the token the proxy refused it before reading it. */
+  setResolveToken(hostResolveToken());
+  const scope = await buildScope(document_, {}, previewBase(filePath));
+  /* This render lands in the PARENT document, so an `<img src="/hero.jpg">` inside it resolves
+     against `index.html` — which is the shell, not the site. Same hook the canvas installs, same
+     context, restored afterwards because the next preview is a different document and a stale
+     `documentDir` would resolve its relative refs against the wrong entry. The version map is
+     read as the render starts, after the reads above: the Library is the many-images screen,
+     and a versioned src is what lets its cards repaint from the browser cache. */
+  const assets = context && { ...context, versions: assetVersionsSnapshot() };
+  setCanvasAssetResolver((value) => resolveAssetRef(value, assets));
+  try {
+    const element = renderNode(document_, scope);
+    return element instanceof HTMLElement ? element : null;
+  } finally {
+    setCanvasAssetResolver(null);
+  }
+}
+
+/**
+ * A project component's preview: an instance given its sample props when it renders with them, else
+ * the first row of a list that draws it (`component-examples.ts`), else none.
+ */
+async function projectComponentPreview(
+  component: ComponentEntry,
+  path: string,
+): Promise<HTMLElement | null> {
+  const definition = await readDefinition(path);
+  if (!definition) {
+    return null;
+  }
+  const props = await componentExampleProps(definition, path);
+  if (props.size > 0 && (await rendersWith(definition, path, props))) {
+    return renderComponentPreview(component, props);
+  }
+  const sample = await componentSampleRow(definition, path);
+  if (sample && (await defineComponent(component))) {
+    return renderDocument(sample.doc, sample.file);
+  }
+  return (await rendersWith(definition, path, props))
+    ? renderComponentPreview(component, props)
+    : null;
+}
+
+/** A project component's definition, or null when its file is not one. */
+export async function readDefinition(path: string): Promise<JxDocument | null> {
+  try {
+    const parsed: unknown = JSON.parse(await getPlatform().readFile(path));
+    /* SAFETY: a project component's `.json` is its definition, a Jx element document; a shape
+       renderNode cannot draw throws into `rendersWith`'s catch, which is "does not render". */
+    return isNonNullObject(parsed) && !Array.isArray(parsed) ? (parsed as JxDocument) : null;
   } catch {
     return null;
   }
 }
 
+/**
+ * Whether `definition` renders given `props` (its sample props, `component-examples.ts`), tried on
+ * a detached copy before a live instance is made.
+ *
+ * A definition may not render with the values it is given: the museum starter's
+ * `<mu-exhibition-card>` formats a `date` that defaults to `""`, and `Intl/formatDate` of an empty
+ * date is a `RangeError`, exactly as `new Intl.DateTimeFormat().format(new Date(""))` is (`spec.md`
+ * §19.4c). An instance renders in its own async `connectedCallback`, where the throw is reported on
+ * the console once per card per paint. The same render, made here synchronously into an element
+ * nobody sees, can be caught, and a definition that cannot render gets no instance preview.
+ */
+export async function rendersWith(
+  definition: JxDocument,
+  path: string,
+  props: ReadonlyMap<string, JsonValue>,
+): Promise<boolean> {
+  let stopRender: (() => void) | null = null;
+  try {
+    setSkipServerFunctions(true);
+    setResolveToken(hostResolveToken());
+    const scope = await buildScope(definition, {}, previewBase(path));
+    for (const [name, value] of props) {
+      scope[name] = value;
+    }
+    /* A template binding that throws no longer unwinds the render (spec.md §6.1): it draws nothing
+       and waits for its data. The trial still has to see it, so the throw is collected for the one
+       synchronous render, as the render critic collects it. */
+    let bindingThrew = false;
+    setTemplateErrorHandler(() => {
+      bindingThrew = true;
+    });
+    // Its own tag would make an instance, and the instance's render is the one that cannot be caught.
+    const { stop } = runScoped(() => renderNode({ ...definition, tagName: "div" }, scope));
+    stopRender = stop;
+    return !bindingThrew;
+  } catch {
+    return false;
+  } finally {
+    setTemplateErrorHandler(null);
+    stopRender?.();
+  }
+}
+
+/** A component whose definition is a JSON file in the project, which is what can be tried first. */
+function isProjectDefinition(component: ComponentEntry): boolean {
+  return component.source !== "npm" && (component.path?.endsWith(".json") ?? false);
+}
+
 /**
  * The preview for one file — a registered component's own preview when there is one, the document
  * render otherwise. Cached; a cache hit does no work at all.
@@ -165,10 +293,17 @@ export async function previewFor(
   }
   let rendered: HTMLElement | null | undefined;
   try {
+    /* A component's `npm:` sidecar, from where the project's packages are served: a preview is a
+       live render in this window, and the runtime would otherwise hand `import()` the `npm:` URL. */
+    setNpmModuleResolver((specifier) => npmModuleUrl(specifier, `${canvasBaseOrigin()}/`));
+    // The project's stylesheet, ready for the box this preview is shown in (`preview-style.ts`).
+    await loadProjectPreviewSheets();
     const component = componentRegistry.find((c: ComponentEntry) => c.path === path);
-    rendered = component
-      ? ((await renderComponentPreview(component)) as HTMLElement | undefined)
-      : await renderDocPreview(path);
+    if (component && isProjectDefinition(component)) {
+      rendered = await projectComponentPreview(component, path);
+    } else {
+      rendered = component ? await renderComponentPreview(component) : await renderDocPreview(path);
+    }
   } catch {
     return undefined;
   }
@@ -219,7 +354,7 @@ export interface PreviewObserver {
  * retained on that path, so there is nothing for the sweep to find.
  */
 export function createPreviewObserver(onVisible: (element: Element) => void): PreviewObserver {
-  if (typeof IntersectionObserver !== "function") {
+  if (!isFunction(globalThis.IntersectionObserver)) {
     return {
       destroy() {
         /* Nothing to disconnect. */

package/src/browse/library-source.ts

@@ -1,11 +1,11 @@
 /**
- * The Library as a {@link GridSource}.
+ * The Content home's scan, as a {@link GridSource}.
  *
- * The Library is one more source over the same contract the CSV, collection, pages and connector
- * grids already use, which is what makes Table a real grid rather than a fifth hand-written table:
- * columns come from {@link libraryColumns}, rows are the scan, and every layout — Cards, Media,
- * Calendar, Board — draws the SAME rows through a different arrangement. A layout switch never
- * re-reads the project.
+ * The scan is one more source over the same contract the CSV, collection, pages and connector grids
+ * already use: columns come from {@link libraryColumns}, rows are the scan, and every view (Table,
+ * Cards, Calendar, Board) draws the SAME rows through a different arrangement. A view switch never
+ * re-reads the project, and neither does showing another collection: the scan covers the project
+ * once, and each collection is a filter over it.
  *
  * It is a **read-only** source, and says so rather than pretending. Renaming, duplicating and
  * deleting a file are real operations with real consequences (a rename rewrites references; a
@@ -16,8 +16,17 @@
 
 import { getPlatform } from "../platform";
 import { projectState } from "../store";
-import { makeGridTabId } from "../grid/grid-source";
-import { scanLibrary } from "./library-model";
+import { workspaceHomeTabId } from "../workspace/workspace-ids";
+import { PAGES_COLLECTION, capitalise, humanName } from "../content/content-collections";
+import { fileToRoute } from "@jxsuite/site/routes";
+import { libraryScanDirs, scanLibrary } from "./library-model";
+import { routedPageExtensions } from "../format/format-host";
+import { DRAFT_FIELD } from "../content/draft-state";
+import { isString } from "@jxsuite/schema/guards";
+import { collectionForFile } from "../content/collection-match";
+import { fileRecords, recordKey } from "../content/file-records";
+import type { ContentTypeSchema } from "@jxsuite/schema/types";
+import type { FileRecord } from "../content/file-records";
 import type { LibraryFile, LibraryScan, ScanFailure } from "./library-model";
 import type {
   CommitResult,
@@ -30,44 +39,283 @@ import type {
 
 /** Why a cell edit is refused — printed by the grid, so the author is told where to go instead. */
 export const LIBRARY_READ_ONLY =
-  "The Library lists files; it does not edit them. Rename, duplicate or delete from the file's " +
-  "context menu, or open the file to edit it.";
-
-/** The Table layout's columns. `path` is the row key and is never editable. */
-export function libraryColumns(): GridColumn[] {
-  return [
-    { editable: false, field: "name", kind: "string", pk: true, title: "Name", widthHint: 260 },
-    { editable: false, field: "category", kind: "string", title: "Category", widthHint: 120 },
-    { editable: false, field: "locale", kind: "string", title: "Locale", widthHint: 90 },
-    { editable: false, field: "type", kind: "string", title: "Type", widthHint: 120 },
-    { editable: false, field: "size", kind: "number", title: "Size", widthHint: 90 },
+  "The Content workspace lists files; it does not edit them in the list. Rename, duplicate or " +
+  "delete from the file's context menu, or open the file to edit it.";
+
+/** Which of an entry's own facts a collection's entries carry, so the Table draws a column for each. */
+export interface EntryColumnFacts {
+  /** Some entry says Draft or Published: the collection has a draft workflow. */
+  status: boolean;
+  /** Some entry is dated by a field of its own. */
+  date: boolean;
+  /** The files are in more than one language (the Pages table draws a Language column). */
+  locale?: boolean;
+  /** The collection's own fields, each drawn as a column after Title, Status and Date. */
+  fields?: readonly EntryFieldColumn[];
+}
+
+/** One schema field the Table draws as a column of its own. */
+export interface EntryFieldColumn {
+  /** The field's name in the entry. */
+  name: string;
+  /** The column heading. */
+  title: string;
+  /**
+   * The field holds a list (`tags: [Patios, Stone]`), which its list text joins with commas. A
+   * Board grouped by it puts an entry under each value, and the Filter matches any one of them.
+   */
+  list?: boolean;
+  /**
+   * A field whose values are measures, not categories: a number (`works: 90`) or a date (`until`).
+   * Translations of one entry repeat them, which is not a grouping, so a Board never groups by
+   * one.
+   */
+  measure?: boolean;
+}
+
+/** The grid field a schema field's column is keyed by, kept apart from the file facts' names. */
+export function entryFieldKey(name: string): string {
+  return `field:${name}`;
+}
+
+/** The schema field a column key names, or null for a column that is no schema field. */
+export function entryFieldOfKey(key: string): string | null {
+  return key.startsWith("field:") ? key.slice("field:".length) : null;
+}
+
+/** At most this many schema fields become columns; the rest are one Edit in grid away. */
+export const ENTRY_FIELD_COLUMN_LIMIT = 6;
+
+/** Formats a list cell cannot show as text: an image is the Cards view's, a body is the editor's. */
+const UNLISTED_FORMATS = new Set(["image", "markdown", "html", "richtext"]);
+
+/** "publishedAt" → "Published at", "course" → "Course". */
+export function fieldTitle(name: string): string {
+  return capitalise(humanName(name));
+}
+
+/**
+ * The schema fields a collection's Table draws, in declaration order: every scalar field except the
+ * ones the Table already names some other way (the title, the date, the draft flag) and the ones
+ * whose value is not text to read in a row (an image, a body, an object).
+ *
+ * @param schema The collection's schema.
+ * @param skip Field names drawn already: the title field and the date field.
+ */
+export function entryFieldColumns(
+  schema: ContentTypeSchema | null | undefined,
+  skip: ReadonlySet<string>,
+): EntryFieldColumn[] {
+  return Object.entries(schema?.properties ?? {})
+    .filter(([name, field]) => {
+      if (skip.has(name) || name === DRAFT_FIELD) {
+        return false;
+      }
+      if (
+        field.type === "object" ||
+        (isString(field.format) && UNLISTED_FORMATS.has(field.format))
+      ) {
+        return false;
+      }
+      // A list of images is a gallery, which no more reads as row text than one image does.
+      const itemFormat = field.items?.format;
+      return (
+        field.type !== "array" ||
+        (field.items?.type === "string" &&
+          !(isString(itemFormat) && UNLISTED_FORMATS.has(itemFormat)))
+      );
+    })
+    .slice(0, ENTRY_FIELD_COLUMN_LIMIT)
+    .map(([name, field]): EntryFieldColumn => {
+      const column: EntryFieldColumn = { name, title: fieldTitle(name) };
+      if (field.type === "array") {
+        column.list = true;
+      }
+      if (
+        field.type === "number" ||
+        field.type === "integer" ||
+        field.format === "date" ||
+        field.format === "date-time"
+      ) {
+        column.measure = true;
+      }
+      return column;
+    });
+}
+
+/**
+ * The Pages table's columns (the Content-Pages board): **Title** (the name the route gives the
+ * page, as the Site panel names it), **URL**, **Template**, **Status** when some page is marked a
+ * draft, **Language** when the pages are in more than one, and **Edited**. No file name and no
+ * path: two pages are both `index.json`, and the URL already says where each one is.
+ */
+function pageColumns(facts?: EntryColumnFacts): GridColumn[] {
+  const columns: GridColumn[] = [
+    { editable: false, field: "title", kind: "string", title: "Title", widthHint: 240 },
+    // The URL is what tells two pages apart: no two routed files publish the same one.
+    { editable: false, field: "url", kind: "string", pk: true, title: "URL", widthHint: 200 },
+    { editable: false, field: "template", kind: "string", title: "Template", widthHint: 140 },
+  ];
+  if (facts?.status) {
+    columns.push({
+      editable: false,
+      field: "status",
+      kind: "string",
+      title: "Status",
+      widthHint: 100,
+    });
+  }
+  if (facts?.locale) {
+    columns.push({
+      editable: false,
+      field: "locale",
+      kind: "string",
+      title: "Language",
+      widthHint: 110,
+    });
+  }
+  columns.push({
+    editable: false,
+    field: "modified",
+    kind: "date",
+    title: "Edited",
+    widthHint: 120,
+  });
+  return columns;
+}
+
+/**
+ * The Table view's columns for a collection. `path` is the row key and is never editable.
+ *
+ * Pages are listed by what an author calls them and where they are published ({@link pageColumns}).
+ * A declared collection leads with what an entry is called and where it stands (its **Title**, then
+ * its **Status** and **Date** when its entries have them), with the file it is stored in after: a
+ * post is "Hello world, Draft", not `hello-world.md`.
+ */
+export function libraryColumns(
+  collection: string = PAGES_COLLECTION,
+  facts?: EntryColumnFacts,
+): GridColumn[] {
+  // The Locale column only when the entries are in more than one language: a column that is empty
+  // On every row of a one-language project is width taken from the Title for nothing.
+  const fileFacts: GridColumn[] = [
+    ...(facts?.locale
+      ? [
+          {
+            editable: false,
+            field: "locale",
+            kind: "string",
+            title: "Locale",
+            widthHint: 90,
+          } as const,
+        ]
+      : []),
     { editable: false, field: "modified", kind: "date", title: "Modified", widthHint: 160 },
     { editable: false, field: "path", kind: "readonly", title: "Path", widthHint: 320 },
   ];
+  if (collection === PAGES_COLLECTION) {
+    return pageColumns(facts);
+  }
+  const entry: GridColumn[] = [
+    { editable: false, field: "title", kind: "string", title: "Title", widthHint: 260 },
+  ];
+  if (facts?.status) {
+    entry.push({
+      editable: false,
+      field: "status",
+      kind: "string",
+      title: "Status",
+      widthHint: 100,
+    });
+  }
+  if (facts?.date) {
+    entry.push({ editable: false, field: "date", kind: "date", title: "Date", widthHint: 120 });
+  }
+  for (const field of facts?.fields ?? []) {
+    entry.push({
+      editable: false,
+      field: entryFieldKey(field.name),
+      kind: "string",
+      title: field.title,
+      widthHint: 140,
+    });
+  }
+  // The Path names the file, so a File column beside it would say the same thing twice.
+  return [...entry, ...fileFacts];
 }
 
 /** One scanned file as a grid row. */
 export function libraryRow(file: LibraryFile): GridRow {
   return {
     cells: {
-      category: file.category,
       // Null, not "": the platform reported no locale directory for this file, and a grid cell
       // Distinguishes "no value" from "the empty string" everywhere else in this contract.
       locale: file.locale ?? null,
       modified: file.modified ?? null,
-      name: file.name,
-      path: file.path,
-      size: file.size ?? null,
-      type: file.type,
+      // The scan reads no file, so a status, a template and a title are the Content home's to add.
+      status: null,
+      template: null,
+      title: file.name,
+      // A page's own URL; an entry's is its collection page's, which the scan does not read.
+      url: file.collection === PAGES_COLLECTION ? fileToRoute(file.path).urlPattern : null,
     },
     key: file.path,
   };
 }
 
 /**
- * A Library source, plus the two questions a grid source cannot ask but the Library must answer:
- * what the scan could not read, and the files behind the rows (the non-table layouts want the typed
- * record, not a cell bag).
+ * A file-backed collection's file, replaced by its records (`content/file-records.ts`): a CSV of
+ * fifteen prices is fifteen entries of its collection, which is what the counts and the Content
+ * home list. The file is read once per scan. One that cannot be read, or whose kind holds no
+ * records Studio reads, stays listed as the file it is.
+ */
+export async function expandFileRecords(
+  files: readonly LibraryFile[],
+  readFile: (path: string) => Promise<string>,
+): Promise<LibraryFile[]> {
+  const expanded = await Promise.all(
+    files.map(async (file): Promise<LibraryFile[]> => {
+      const match = file.collection === null ? null : collectionForFile(file.path);
+      if (!match?.fileBacked) {
+        return [file];
+      }
+      let text: string;
+      try {
+        text = await readFile(file.path);
+      } catch {
+        return [file];
+      }
+      const records = fileRecords(file.path, text, match.def.schema);
+      if (records === null) {
+        return [file];
+      }
+      return records.map((record) => recordRow(file, record));
+    }),
+  );
+  return expanded.flat();
+}
+
+/** One record of `file`, listed as a row of its own. */
+function recordRow(file: LibraryFile, record: FileRecord): LibraryFile {
+  return {
+    ...file,
+    name: record.title,
+    path: recordKey(file.path, record.index),
+    record: { fields: record.fields, row: record.row, source: file.path },
+  };
+}
+
+/** {@link expandFileRecords} over a whole scan, reading through the platform. */
+async function withRecords(scan: LibraryScan): Promise<LibraryScan> {
+  const platform = getPlatform();
+  const files = await expandFileRecords(scan.files, (path) => platform.readFile(path));
+  return { ...scan, files };
+}
+
+/**
+ * The scan's source, plus the two questions a grid source cannot ask but the Content home must
+ * answer: what the scan could not read, and the files behind the rows (the non-table layouts want
+ * the typed record, not a cell bag).
  */
 export interface LibrarySource extends GridSource {
   /** The scanned files, in path order. Empty before the first {@link GridSource.rows} call. */
@@ -76,15 +324,19 @@ export interface LibrarySource extends GridSource {
   failures: () => readonly ScanFailure[];
   /** Whether a scan has completed at least once — "not loaded yet" is not "empty". */
   scanned: () => boolean;
-}
-
-/** The Library's tab id. One Library per window; category and layout are view state, not identity. */
-export function libraryTabId(): string {
-  return makeGridTabId({ kind: "library" });
+  /**
+   * Whether the completed scan walked a different directory list than the project has now.
+   *
+   * The list is read when the project's directories load and grows when a collection is declared,
+   * and either can happen after a scan already finished: a window restored straight into Content
+   * asks for its rows before the project's directories have loaded, and the walk of none is an
+   * answer of none. A stale scan is not an empty project, so its owner discards it.
+   */
+  stale: () => boolean;
 }
 
 /**
- * Build the Library source. The scan is lazy: nothing is read until the first `rows()`.
+ * Build the scan's source. The scan is lazy: nothing is read until the first `rows()`.
  *
  * @param {() => readonly string[]} [dirs] Project directories to scan, injectable for tests and for
  *   the perf measurement; defaults to the open project's own list.
@@ -92,8 +344,12 @@ export function libraryTabId(): string {
 export function createLibrarySource(dirs?: () => readonly string[]): LibrarySource {
   let scan: LibraryScan | null = null;
   let inFlight: Promise<LibraryScan> | null = null;
+  /** The directory list the cached scan walked, joined: the key {@link LibrarySource.stale} tests. */
+  let scannedKey: string | null = null;
 
-  const projectDirs = dirs ?? (() => (projectState?.projectDirs ?? []) as readonly string[]);
+  const projectDirs =
+    dirs ??
+    (() => libraryScanDirs(projectState?.projectDirs ?? [], projectState?.projectConfig ?? null));
 
   async function ensureScan(): Promise<LibraryScan> {
     if (scan) {
@@ -101,11 +357,21 @@ export function createLibrarySource(dirs?: () => readonly string[]): LibrarySour
     }
     // Coalesce: five layouts and a command can all ask at once on the first paint, and the answer
     // Is one walk of the project, not six.
-    inFlight ??= scanLibrary(projectDirs(), getPlatform()).then((result) => {
-      scan = result;
-      inFlight = null;
-      return result;
-    });
+    const walked = projectDirs();
+    /* A collection source the project's own list does not hold may not exist yet (a collection
+       declared before its first entry): its absence is an empty collection, never a failure. */
+    const conventional = new Set(dirs ? walked : (projectState?.projectDirs ?? []));
+    const optional = new Set(walked.filter((dir) => !conventional.has(dir)));
+    // The extensions first: a page is the file the build routes, and that is a fact of the formats.
+    inFlight ??= routedPageExtensions()
+      .then((pageExtensions) => scanLibrary(walked, getPlatform(), optional, pageExtensions))
+      .then(withRecords)
+      .then((result) => {
+        scan = result;
+        scannedKey = walked.join("\n");
+        inFlight = null;
+        return result;
+      });
     return inFlight;
   }
 
@@ -134,8 +400,8 @@ export function createLibrarySource(dirs?: () => readonly string[]): LibrarySour
     },
     failures: () => scan?.failures ?? [],
     files: () => scan?.files ?? [],
-    id: libraryTabId(),
-    label: "Library",
+    id: workspaceHomeTabId("content"),
+    label: "Content",
     async refresh() {
       scan = null;
       inFlight = null;
@@ -146,5 +412,6 @@ export function createLibrarySource(dirs?: () => readonly string[]): LibrarySour
       return { rows: result.files.map((file) => libraryRow(file)), total: result.files.length };
     },
     scanned: () => scan !== null,
+    stale: () => scan !== null && scannedKey !== projectDirs().join("\n"),
   };
 }