@jxsuite/parser 1.4.0 → 1.5.0

package/src/content-loader.ts

@@ -20,6 +20,7 @@
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { basename, dirname, extname, resolve } from "node:path";
 import { assetUrlFor } from "@jxsuite/schema/asset-paths";
+import { resolveI18n } from "@jxsuite/schema/locale";
 import type { AssetMount } from "@jxsuite/schema/asset-paths";
 import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
 import type { FormatEntry, FormatHostIO, FormatRegistry } from "@jxsuite/schema/format-registry";
@@ -29,6 +30,7 @@ import type {
   JxMutableNode,
   ProjectConfig,
 } from "@jxsuite/schema/types";
+import { coerceEntryDates, isCoercedDate, isDateFormat } from "./dates.ts";
 import type { ContentLoaderEntry, ContentTypeDef } from "./types.ts";
 
 export type { ContentEntry, ContentLoaderEntry, TocEntry } from "./types.ts";
@@ -56,6 +58,11 @@ export interface ResolvePathsContext {
   projectConfig?: ProjectConfig;
   /** Absolute project root directory. */
   root: string;
+  /**
+   * The locale of the route being expanded, when the project has any. Only a localized collection
+   * reads it — it is the discriminator between two translations sharing an id.
+   */
+  locale?: string | null;
 }
 
 /** The `$paths` value shape routed to this extension by its `contentType` discriminator. */
@@ -110,6 +117,70 @@ function discoverJSONFiles(resolvedSource: string): string[] {
 
 // ─── Asset mounts and content-relative references ────────────────────────────
 
+/**
+ * The placeholder a content type's `source` may carry to say "one directory per locale".
+ *
+ * `./blog/{locale}/` is one content type spread over N directories, not N content types. That
+ * distinction is what keeps a translated post the same post: it keeps one schema, one set of
+ * relationship targets, and one name in `$paths`, and differs only in which directory it was read
+ * from — which is exactly the model `site-architecture.md` §13 uses for routes.
+ */
+export const LOCALE_PLACEHOLDER = "{locale}";
+
+/**
+ * The locales a `{locale}` source expands over, or `[]` when the project declares none.
+ *
+ * The **canonical** tags, from the same resolver the compiler and Studio run — it lives in
+ * `@jxsuite/schema/locale` precisely so that three hosts cannot disagree about what `EN-us` means.
+ * This module used to read the raw list, on the reasoning that canonicalization was the compiler's
+ * job; that was true when the function was the compiler's, and it left this the one place where a
+ * locale's spelling came from the config rather than from the parser.
+ *
+ * @param {ProjectConfig | undefined} projectConfig
+ * @returns {string[]}
+ */
+export function localesForExpansion(projectConfig: ProjectConfig | undefined): string[] {
+  return resolveI18n(projectConfig ?? {}).i18n?.locales ?? [];
+}
+
+/**
+ * The directory a locale's entries live in, out of the spellings that can legitimately be on disk.
+ *
+ * A locale directory is matched **case-insensitively**, because two writers name it and they
+ * differ: a project that declared `fr-CA` most likely typed `fr-CA/`, while Studio creates
+ * `content/<type>/fr-ca/` — lowercase, because a page directory becomes a URL and the site's own
+ * URLs are lowercase (`site-architecture.md` §13.2). Reading only one of the two spellings makes a
+ * translation somebody just created invisible to the build, with no error: the directory is there,
+ * the entries are there, and the collection loads none of them.
+ *
+ * The canonical spelling is preferred so an existing tree keeps its own answer, and a scan of the
+ * parent runs only when neither exact spelling exists.
+ *
+ * @param {string} root
+ * @param {string} source - The `{locale}`-bearing source
+ * @param {string} locale - Canonical tag
+ * @returns {string} The source with `{locale}` replaced by the spelling that is on disk
+ */
+export function localeSource(root: string, source: string, locale: string): string {
+  const candidates = [locale, locale.toLowerCase()];
+  for (const spelling of candidates) {
+    const path = source.split(LOCALE_PLACEHOLDER).join(spelling);
+    if (existsSync(resolve(root, path))) {
+      return path;
+    }
+  }
+  const parent = resolve(root, source.slice(0, source.indexOf(LOCALE_PLACEHOLDER)));
+  if (existsSync(parent) && statSync(parent).isDirectory()) {
+    const match = readdirSync(parent).find((name) => name.toLowerCase() === locale.toLowerCase());
+    if (match !== undefined) {
+      return source.split(LOCALE_PLACEHOLDER).join(match);
+    }
+  }
+  /* Nothing on disk: the canonical spelling, so the miss is reported against the name that was
+     declared rather than against a spelling nobody wrote. */
+  return source.split(LOCALE_PLACEHOLDER).join(locale);
+}
+
 /** The project.json section key this class owns; also the URL namespace for its asset mounts. */
 const SECTION_KEY = "content";
 
@@ -140,13 +211,37 @@ function isNonRelativeRef(value: string): boolean {
  * @param {string} root - Absolute project root directory
  * @returns {AssetMount[]} One mount per eligible content type, in declaration order
  */
-export function contentAssetMounts(section: ContentSection, root: string): AssetMount[] {
+export function contentAssetMounts(
+  section: ContentSection,
+  root: string,
+  projectConfig?: ProjectConfig,
+): AssetMount[] {
   const mounts: AssetMount[] = [];
+  const locales = localesForExpansion(projectConfig);
   for (const [name, contentTypeDef] of Object.entries(section ?? {})) {
     const source = contentTypeDef?.source;
     if (!source || source.startsWith("http://") || source.startsWith("https://")) {
       continue;
     }
+    /*
+     * A localized source is N directories, so it is N mounts — published under
+     * `/content/<type>/<locale>` so a French post's `./hero.png` and its English translation's
+     * cannot collide at one URL.
+     */
+    if (source.includes(LOCALE_PLACEHOLDER)) {
+      for (const locale of locales) {
+        if (!SAFE_TYPE_NAME.test(locale)) {
+          continue;
+        }
+        const dir = resolve(root, localeSource(root, source, locale))
+          .split("\\")
+          .join("/");
+        if (SAFE_TYPE_NAME.test(name) && existsSync(dir) && statSync(dir).isDirectory()) {
+          mounts.push({ dir, urlPrefix: `/${SECTION_KEY}/${name}/${locale}` });
+        }
+      }
+      continue;
+    }
     if (!SAFE_TYPE_NAME.test(name)) {
       console.warn(
         `Content type "${name}": name is not URL-safe — its source directory is not published ` +
@@ -310,14 +405,59 @@ export async function loadContentSection(
   section: ContentSection,
   root: string,
   formats: FormatRegistry,
+  projectConfig?: ProjectConfig,
 ): Promise<Map<string, ContentLoaderEntry[]>> {
   const contentTypes = new Map<string, ContentLoaderEntry[]>();
   const mounts = new Map(
-    contentAssetMounts(section, root).map((mount) => [mount.urlPrefix.split("/").pop()!, mount]),
+    contentAssetMounts(section, root, projectConfig).map((mount) => [
+      /*
+       * The path below `/content/` — `<type>` for a plain source, `<type>/<locale>` for a
+       * localized one — which is exactly the key each lookup below builds. Keying by the LAST
+       * segment made every localized mount unreachable (`posts/fr` never matching `fr`), so a
+       * translated entry's `./hero.png` was left unrewritten; and it collided any two types that
+       * shared a locale.
+       */
+      mount.urlPrefix.slice(`/${SECTION_KEY}/`.length),
+      mount,
+    ]),
   );
+  const locales = localesForExpansion(projectConfig);
   for (const [name, contentTypeDef] of Object.entries(section)) {
-    const entries = await loadContentType(name, contentTypeDef, root, formats, mounts.get(name));
-    contentTypes.set(name, entries);
+    const source = contentTypeDef?.source;
+    if (typeof source !== "string" || !source.includes(LOCALE_PLACEHOLDER)) {
+      const entries = await loadContentType(name, contentTypeDef, root, formats, mounts.get(name));
+      contentTypes.set(name, entries);
+      continue;
+    }
+    /*
+     * One content type, N directories. Each pass loads a real path and stamps the locale it came
+     * from onto every entry, which is the only thing distinguishing two translations that share an
+     * id — `resolvePaths` reads it back to expand the right ones under a locale-prefixed route.
+     */
+    if (locales.length === 0) {
+      console.warn(
+        `Content type "${name}": source "${source}" uses ${LOCALE_PLACEHOLDER}, but the project ` +
+          `declares no i18n locales — nothing to expand it over, so no entries were loaded.`,
+      );
+      contentTypes.set(name, []);
+      continue;
+    }
+    const all: ContentLoaderEntry[] = [];
+    for (const locale of locales) {
+      const localized = { ...contentTypeDef, source: localeSource(root, source, locale) };
+      const entries = await loadContentType(
+        name,
+        localized,
+        root,
+        formats,
+        mounts.get(`${name}/${locale}`),
+      );
+      for (const entry of entries) {
+        entry._meta = { ...entry._meta, locale };
+      }
+      all.push(...entries);
+    }
+    contentTypes.set(name, all);
   }
   return contentTypes;
 }
@@ -470,8 +610,15 @@ async function loadContentType(
     entries.push(...fileEntries);
   }
 
-  // Validate entries against schema if present
+  /*
+   * Coerce declared date fields before validating. This is the one point in the pipeline that holds
+   * both the entries and the schema: `Csv.load` receives a schema and `Markdown.load` does not, so
+   * doing it per-format would mean doing it twice and missing every third-party format class.
+   */
   if (schema) {
+    for (const warning of coerceEntryDates(entries, schema, name)) {
+      console.warn(warning.message);
+    }
     validateEntries(entries, schema, name);
   }
 
@@ -526,7 +673,12 @@ function validateEntries(
         continue;
       }
 
-      if (def.type === "string" && typeof value !== "string") {
+      if (isDateFormat(def.format) && typeof value === "string" && !isCoercedDate(value)) {
+        console.warn(
+          `Content validation: "${contentTypeName}/${entry.id}" field "${field}" is declared ` +
+            `${def.format} but "${value}" was not coerced — it will sort and filter as plain text.`,
+        );
+      } else if (def.type === "string" && typeof value !== "string") {
         console.warn(
           `Content validation: "${contentTypeName}/${entry.id}" field "${field}" expected string, got ${typeof value}`,
         );
@@ -652,7 +804,12 @@ export class Content {
     ctx: ProjectDataContext,
   ): Promise<Map<string, ContentLoaderEntry[]>> {
     const section = (sectionValue ?? {}) as ContentSection;
-    const data = await loadContentSection(section, ctx.root, ctx.registry.formats);
+    const data = await loadContentSection(
+      section,
+      ctx.root,
+      ctx.registry.formats,
+      ctx.projectConfig,
+    );
     resolveContentTypeRefs(data, section);
     return data;
   }
@@ -666,14 +823,23 @@ export class Content {
    * @param {{ projectConfig?: ProjectConfig; root: string }} ctx - Host context
    * @returns {AssetMount[]} One mount per content type with a local directory source
    */
-  static assets(sectionValue: unknown, ctx: { root: string }): AssetMount[] {
-    return contentAssetMounts((sectionValue ?? {}) as ContentSection, ctx.root);
+  static assets(
+    sectionValue: unknown,
+    ctx: { root: string; projectConfig?: ProjectConfig },
+  ): AssetMount[] {
+    return contentAssetMounts((sectionValue ?? {}) as ContentSection, ctx.root, ctx.projectConfig);
   }
 
   /**
    * Expand a content-type `$paths` source into route-param maps: one `{ [param]: value }` per
    * entry, with `param` defaulting to "slug" and `field` to "id" (the entry id).
    *
+   * Each map also carries the entry's own `_meta`, under that reserved name. `_meta` is not a route
+   * parameter and the host strips it before substitution — it is how a fact about the _entry_
+   * reaches a route that would otherwise know only about the template that generated it. The one
+   * that matters today is `mtime`: without it every post in a collection reports the template's
+   * timestamp in `<lastmod>`, so the whole archive looks edited whenever the template is.
+   *
    * @param {ContentPathsSource} pathsDef - The `$paths` value ({ contentType, param?, field? })
    * @param {ResolvePathsContext} ctx - Host context ({ data, projectConfig, root })
    * @returns {Promise<Record<string, unknown>[]>} Array of route-param objects
@@ -691,10 +857,30 @@ export class Content {
     }
     const param = pathsDef.param ?? "slug";
     const field = pathsDef.field ?? "id";
-    return entries
-      .map((entry) => ({
-        [param]: field === "id" ? entry.id : (entry.data[field] ?? entry.id),
-      }))
-      .filter((p) => p[param]);
+    /*
+     * A localized collection holds every language at once, and two translations of one post share
+     * an id — so expanding all of them under `/fr/[slug]` would emit each route twice and let the
+     * second overwrite the first. The route's own locale is the discriminator, and it is applied
+     * only when the entries actually carry one: an unlocalized collection is untouched.
+     */
+    const localized = entries.some((entry) => entry._meta?.locale !== undefined);
+    const wanted = ctx.locale;
+    const scoped =
+      localized && typeof wanted === "string"
+        ? entries.filter((entry) => entry._meta?.locale === wanted)
+        : entries;
+    const paths: Record<string, unknown>[] = [];
+    for (const entry of scoped) {
+      const value = field === "id" ? entry.id : (entry.data[field] ?? entry.id);
+      if (!value) {
+        continue;
+      }
+      const pathEntry: Record<string, unknown> = { [param]: value };
+      if (entry._meta !== undefined) {
+        pathEntry._meta = entry._meta;
+      }
+      paths.push(pathEntry);
+    }
+    return paths;
   }
 }

package/src/content.ts

@@ -6,6 +6,7 @@
  * queryContentType, findEntry) used by both the classes and the server endpoint.
  */
 
+import { parseComparable } from "./dates.ts";
 import type { ContentLoaderEntry } from "./types.ts";
 
 interface CollectionConfig {
@@ -31,7 +32,11 @@ interface EntryConfig {
     [k: string]: unknown;
   };
   _document?: {
-    route?: { _pathParams?: Record<string, string> };
+    route?: {
+      _pathParams?: Record<string, string>;
+      /** The language this route serves, when the project declares any (§13.4). */
+      locale?: string | null;
+    };
     [k: string]: unknown;
   };
   [k: string]: unknown;
@@ -76,17 +81,26 @@ export function evaluateFilterRule(
       }
       return typeof actual === "string" && !actual.includes(String(rule.value ?? ""));
     }
+    /*
+     * `Number()` on both sides made every date comparison false, since NaN compares false against
+     * everything. `parseComparable` keeps two normalized dates in string space, where RFC 3339
+     * compares chronologically.
+     */
     case ">": {
-      return Number(actual) > Number(rule.value);
+      const [a, b] = parseComparable(actual, rule.value);
+      return a > b;
     }
     case "<": {
-      return Number(actual) < Number(rule.value);
+      const [a, b] = parseComparable(actual, rule.value);
+      return a < b;
     }
     case ">=": {
-      return Number(actual) >= Number(rule.value);
+      const [a, b] = parseComparable(actual, rule.value);
+      return a >= b;
     }
     case "<=": {
-      return Number(actual) <= Number(rule.value);
+      const [a, b] = parseComparable(actual, rule.value);
+      return a <= b;
     }
     default: {
       return true;
@@ -225,9 +239,26 @@ export class ContentEntry {
       return null;
     }
 
+    /*
+     * Scoped to the route's language, exactly as `resolvePaths` scopes an expansion and for the
+     * same reason: two translations of one entry share an id (site-architecture.md §13.3), so an
+     * unscoped lookup answers with whichever language was loaded first. Under `/fr-ca/…` that is
+     * the English copy, rendered on a page whose `<html lang>` and every `hreflang` say French —
+     * a defect no error reports and every reader of the other language sees.
+     *
+     * Applied only when the entries actually carry a locale: an unlocalized collection is not in
+     * one language, and filtering it by the route's would empty it.
+     */
+    const wanted = _document?.route?.locale;
+    const localized = entries.some((e: ContentLoaderEntry) => e._meta?.locale !== undefined);
+    const scoped =
+      localized && typeof wanted === "string"
+        ? entries.filter((e: ContentLoaderEntry) => e._meta?.locale === wanted)
+        : entries;
+
     if (field && field !== "id") {
-      return entries.find((e: ContentLoaderEntry) => e.data[field] === resolvedId) ?? null;
+      return scoped.find((e: ContentLoaderEntry) => e.data[field] === resolvedId) ?? null;
     }
-    return findEntry(entries, resolvedId as string);
+    return findEntry(scoped, resolvedId as string);
   }
 }

package/src/dates.ts

@@ -0,0 +1,184 @@
+/**
+ * Date coercion for content entries — the one pass that gives a `format: "date"` field a value the
+ * rest of the pipeline can actually compare.
+ *
+ * **Why a normalized string and not a `Date`.** `JSON.stringify(new Date("2025-03-04"))` yields an
+ * instant, so a Studio save would silently rewrite `2025-03-04` to `2025-03-04T00:00:00.000Z` —
+ * which is _March 3_ anywhere west of UTC. That off-by-one is the classic blog-date bug, and a
+ * format that round-trips through JSON cannot afford it. A `Temporal.PlainDate` is semantically
+ * right and fails differently: `<` and `>` on one yield NaN, and the sort in `content.ts` compares
+ * with exactly those.
+ *
+ * **Why UTC for date-times.** Mixed offsets do not sort lexicographically —
+ * `2025-03-04T01:00:00+02:00` sorts _after_ `2025-03-04T00:00:00Z` as text and is _earlier_ in
+ * time. Normalizing to `Z` makes the existing raw string comparison correct by construction rather
+ * than correct by accident.
+ *
+ * **Why an ambiguous string is refused rather than guessed.** `03/04/2025` is March 4th or April
+ * 3rd depending on where the author lives, and `new Date()` resolves it by implementation-defined
+ * rules. Silently picking one is the bug this pass exists to prevent, so refusing it _is_ the
+ * feature.
+ *
+ * @docs framework/site/content-collections
+ */
+
+import type { ContentTypeSchema } from "@jxsuite/schema/types";
+import type { ContentLoaderEntry } from "./types.ts";
+
+/** The two JSON Schema `format` values that carry build behavior. */
+export const DATE_FORMATS = ["date", "date-time"] as const;
+export type DateFormat = (typeof DATE_FORMATS)[number];
+
+export function isDateFormat(format: unknown): format is DateFormat {
+  return typeof format === "string" && (DATE_FORMATS as readonly string[]).includes(format);
+}
+
+/** `YYYY-MM-DD`, with no time part. */
+const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
+/** RFC 3339 date-time: a date, a `T`, a time, and an offset or `Z`. */
+const RFC_3339 = /^\d{4}-\d{2}-\d{2}[Tt ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?([Zz]|[+-]\d{2}:\d{2})?$/;
+
+function pad(n: number, width = 2): string {
+  return String(n).padStart(width, "0");
+}
+
+/** A `Date` to `YYYY-MM-DD`, read in UTC so the calendar day matches what was stored. */
+function toDateOnly(d: Date): string {
+  return `${pad(d.getUTCFullYear(), 4)}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())}`;
+}
+
+/** A `Date` to RFC 3339 in UTC, without fractional seconds. */
+function toInstant(d: Date): string {
+  return `${toDateOnly(d)}T${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}:${pad(d.getUTCSeconds())}Z`;
+}
+
+/**
+ * Coerce one authored value to RFC 3339, or null when it is not an unambiguous date.
+ *
+ * Accepts, in order: a `Date` (YAML frontmatter parsers routinely produce one for an unquoted
+ * `date: 2025-03-04`), an RFC 3339 string, and a bare `YYYY-MM-DD`. Everything else is refused.
+ */
+export function parseDateValue(value: unknown, format: DateFormat): string | null {
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime())
+      ? null
+      : format === "date"
+        ? toDateOnly(value)
+        : toInstant(value);
+  }
+  if (typeof value !== "string") {
+    return null;
+  }
+  const text = value.trim();
+  if (text === "") {
+    return null;
+  }
+
+  if (DATE_ONLY.test(text)) {
+    // A bare date has no zone. Reading it as UTC midnight is the only reading that does not move
+    // The calendar day, which is the whole point of a date-only field.
+    const d = new Date(`${text}T00:00:00Z`);
+    if (Number.isNaN(d.getTime())) {
+      return null;
+    }
+    return format === "date" ? text : toInstant(d);
+  }
+
+  if (RFC_3339.test(text)) {
+    // A date-time with no offset is a local time with no way to know which locality, so it is read
+    // As UTC rather than as the build machine's zone — a build must not depend on where it runs.
+    const normalized = /[Zz]|[+-]\d{2}:\d{2}$/.test(text) ? text : `${text.replace(" ", "T")}Z`;
+    const d = new Date(normalized);
+    if (Number.isNaN(d.getTime())) {
+      return null;
+    }
+    return format === "date" ? toDateOnly(d) : toInstant(d);
+  }
+
+  return null;
+}
+
+/** Whether a value is already in one of the two normalized forms this module emits. */
+export function isCoercedDate(value: string): boolean {
+  return DATE_ONLY.test(value) || RFC_3339.test(value);
+}
+
+/** Where a coercion pass records what it could not read. */
+export interface DateCoercionWarning {
+  entryId: string;
+  field: string;
+  value: unknown;
+  message: string;
+}
+
+/**
+ * Coerce every schema-declared date field on every entry, in place.
+ *
+ * The original text is kept at `entry._meta.rawDates[field]`, because an events collection that
+ * genuinely means "7pm local" needs it back and the normalized instant has thrown that away.
+ */
+export function coerceEntryDates(
+  entries: ContentLoaderEntry[],
+  schema: ContentTypeSchema | undefined,
+  contentTypeName: string,
+): DateCoercionWarning[] {
+  const warnings: DateCoercionWarning[] = [];
+  const properties = schema?.properties;
+  if (!properties) {
+    return warnings;
+  }
+
+  const dateFields: [string, DateFormat][] = Object.entries(properties)
+    .map(([field, def]): [string, unknown] => [field, (def as { format?: unknown }).format])
+    .filter((pair): pair is [string, DateFormat] => isDateFormat(pair[1]));
+  if (dateFields.length === 0) {
+    return warnings;
+  }
+
+  for (const entry of entries) {
+    for (const [field, format] of dateFields) {
+      const raw = entry.data[field];
+      if (raw === undefined || raw === null || raw === "") {
+        continue;
+      }
+      const coerced = parseDateValue(raw, format);
+      if (coerced === null) {
+        warnings.push({
+          entryId: entry.id,
+          field,
+          message:
+            `Content dates: "${contentTypeName}/${entry.id}" field "${field}" is ` +
+            `${JSON.stringify(raw)}, which is not an unambiguous ${format}. Write it as ` +
+            `${format === "date" ? "YYYY-MM-DD" : "YYYY-MM-DDTHH:MM:SSZ"} — a form like ` +
+            `"03/04/2025" means two different days depending on who reads it, so it is left as ` +
+            `authored rather than guessed.`,
+          value: raw,
+        });
+        continue;
+      }
+      if (coerced !== raw) {
+        entry._meta ??= {};
+        entry._meta.rawDates ??= {};
+        entry._meta.rawDates[field] = raw;
+      }
+      entry.data[field] = coerced;
+    }
+  }
+  return warnings;
+}
+
+/**
+ * Comparable form for a filter comparison.
+ *
+ * `>` and `<` pushed both sides through `Number()`, so a date comparison was ALWAYS false — `NaN`
+ * compares false against everything. Normalized RFC 3339 strings compare chronologically as text,
+ * so the fix is to notice when both sides are dates and stay in string space.
+ */
+export function parseComparable(a: unknown, b: unknown): [number, number] | [string, string] {
+  const aDate = typeof a === "string" && (DATE_ONLY.test(a) || RFC_3339.test(a));
+  const bDate = typeof b === "string" && (DATE_ONLY.test(b) || RFC_3339.test(b));
+  if (aDate && bDate) {
+    return [a as string, b as string];
+  }
+  return [Number(a), Number(b)];
+}

package/src/markdown.ts

@@ -82,7 +82,7 @@ export class Markdown {
     options: MarkdownLoadOptions = {},
   ): Promise<ContentLoaderEntry[]> {
     const { processMarkdown } = await import("./md.ts");
-    const { readFileSync } = await import("node:fs");
+    const { readFileSync, statSync } = await import("node:fs");
     const source = readFileSync(path, "utf8");
     const result = processMarkdown(source, path, {
       ...(options.directives !== undefined && { directives: options.directives }),
@@ -92,6 +92,18 @@ export class Markdown {
       ...(options.sourceRoot !== undefined && { sourceRoot: options.sourceRoot }),
     });
     const _meta: ContentLoaderEntry["_meta"] = {};
+    /*
+     * The modification time is the only date a file always has. A feed falls back to it when the
+     * frontmatter carries none, and it is what would let the sitemap stop giving every page
+     * generated from one template that template's `<lastmod>`.
+     */
+    try {
+      _meta.mtime = statSync(path)
+        .mtime.toISOString()
+        .replace(/\.\d{3}Z$/, "Z");
+    } catch {
+      // A format class may be handed content that is not on disk; an absent mtime is not an error.
+    }
     if (result.$excerpt != null) {
       _meta.excerpt = result.$excerpt;
     }

package/src/md.ts

@@ -18,6 +18,7 @@ import remarkParseFrontmatter from "remark-parse-frontmatter";
 import remarkGfm from "remark-gfm";
 import remarkDirective from "remark-directive";
 import { readFileSync } from "node:fs";
+import { DEFAULT_FORMAT_LOCALE } from "@jxsuite/schema/intl";
 import { basename, extname, relative, resolve as resolvePath } from "node:path";
 import { globSync } from "glob";
 import { assignHeadingIds, mdastNodeToJx } from "./transpile.ts";
@@ -82,15 +83,62 @@ function mdastToString(node: MdastNode): string {
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 
+/** Average reading speed. See {@link readingTime} for why this is one number and not a table. */
+const WORDS_PER_MINUTE = 200;
+
+/**
+ * One segmenter, built once.
+ *
+ * The locale is fixed rather than the host's: word boundaries are a property of the text, and a
+ * word count that changed with the build machine's locale would be the same determinism bug the
+ * `Intl` helpers exist to avoid.
+ */
+const WORD_SEGMENTER = new Intl.Segmenter(DEFAULT_FORMAT_LOCALE, { granularity: "word" });
+
+/** A segment is a word when it carries a letter or a digit. See {@link countWords}. */
+const WORD_LIKE = /[\p{L}\p{N}]/u;
+
+/**
+ * Count the words in a string by **segmenting** it, not by splitting on whitespace (UAX #29).
+ *
+ * Splitting on `\s+` assumes a script that puts spaces between its words. Japanese, Chinese and
+ * Thai do not, so an entire article in any of them counted as **one word** — and therefore one
+ * minute to read, whatever its length. `Intl.Segmenter` applies the Unicode word-boundary rules.
+ *
+ * **A segment counts when it contains a letter or a digit, rather than when `isWordLike` says so.**
+ * That property is what `isWordLike` is defined to mean, but Bun's engine answers `false` for a
+ * mixed alphanumeric segment — `w0`, `v3`, `h1` — so trusting it would drop every token of that
+ * shape from the count, silently and only for some documents. The predicate is spelled out because
+ * it has to be correct on the runtime this actually runs on.
+ *
+ * This runs in the parser under Bun, so there is no browser-support question to weigh.
+ *
+ * @param {string} text
+ * @returns {number}
+ */
+function countWords(text: string): number {
+  let words = 0;
+  for (const { segment } of WORD_SEGMENTER.segment(text)) {
+    if (WORD_LIKE.test(segment)) {
+      words += 1;
+    }
+  }
+  return words;
+}
+
 /**
- * Estimate reading time based on word count (~200 wpm average).
+ * Estimate reading time from the word count.
+ *
+ * **200 wpm, and the limitation is stated rather than modelled.** Real reading speed varies by
+ * script, by density and by reader — a Japanese character carries more than a Latin one, so a
+ * per-script table would be more accurate and would also be a table of guesses nobody could verify.
+ * One honest constant that the docs name beats a plausible one that they cannot.
  *
  * @param {string} text
  * @returns {number} Minutes (rounded up, minimum 1)
  */
 function readingTime(text: string) {
-  const words = text.split(/\s+/).filter(Boolean).length;
-  return Math.max(1, Math.ceil(words / 200));
+  return Math.max(1, Math.ceil(countWords(text) / WORDS_PER_MINUTE));
 }
 
 /**
@@ -199,7 +247,7 @@ export function processMarkdown(
     $excerpt: excerpt,
     $readingTime: readingTime(plainText),
     $toc: toc,
-    $wordCount: plainText.split(/\s+/).filter(Boolean).length,
+    $wordCount: countWords(plainText),
     frontmatter,
     path: filePath,
     slug,