@bendyline/docblocks 2.7.8 → 2.7.9

package/THIRD_PARTY_NOTICES.txt

@@ -14,8 +14,8 @@ This notice is included in the published npm tarball. Transitive packages instal
 
 | Package | Version | License | Source |
 | --- | --- | --- | --- |
-| @bendyline/squisq | 2.13.6 | MIT | https://github.com/bendyline/squisq |
-| @bendyline/squisq-graph | 2.13.0 | MIT | https://github.com/bendyline/squisq |
+| @bendyline/squisq | 2.13.8 | MIT | https://github.com/bendyline/squisq |
+| @bendyline/squisq-graph | 2.13.1 | MIT | https://github.com/bendyline/squisq |
 | @types/debug | 4.1.12 | MIT | https://github.com/DefinitelyTyped/DefinitelyTyped |
 | @types/hast | 3.0.4 | MIT | https://github.com/DefinitelyTyped/DefinitelyTyped |
 | @types/katex | 0.16.8 | MIT | https://github.com/DefinitelyTyped/DefinitelyTyped |
@@ -133,7 +133,7 @@ This notice is included in the published npm tarball. Transitive packages instal
 Package-local license, copying, and notice files are reproduced below. Where a published package omits its repository license, the reviewed aggregate or README identified in `Source files` supplies the retained material.
 
 ==============================================================================
-Components: @bendyline/squisq-graph@2.13.0, @bendyline/squisq@2.13.6
+Components: @bendyline/squisq-graph@2.13.1, @bendyline/squisq@2.13.8
 Source files: node_modules/@bendyline/squisq-graph/LICENSE, node_modules/@bendyline/squisq/LICENSE
 ==============================================================================
 MIT License
@@ -159,7 +159,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
 ==============================================================================
-Components: @bendyline/squisq-graph@2.13.0
+Components: @bendyline/squisq-graph@2.13.1
 Source files: node_modules/@bendyline/squisq-graph/NOTICE.md
 ==============================================================================
 # Third-Party Notices for @bendyline/squisq-graph
@@ -177,7 +177,7 @@ This package has no third-party runtime dependencies. The layout engine and its
 worker entry are Squisq-authored (MIT).
 
 ==============================================================================
-Components: @bendyline/squisq-graph@2.13.0
+Components: @bendyline/squisq-graph@2.13.1
 Source files: node_modules/@bendyline/squisq-graph/THIRD_PARTY_LICENSES.txt
 ==============================================================================
 THIRD-PARTY LICENSES FOR @bendyline/squisq-graph
@@ -189,7 +189,7 @@ repository license, the pinned upstream copy is vendored and identified below.
 COMPONENTS
 
 ==============================================================================
-Components: @bendyline/squisq@2.13.6
+Components: @bendyline/squisq@2.13.8
 Source files: node_modules/@bendyline/squisq/NOTICE.md
 ==============================================================================
 # Third-Party Notices for @bendyline/squisq
@@ -220,7 +220,7 @@ third-party license texts for bundled code and data are shipped in
 THIRD_PARTY_LICENSES.txt.
 
 ==============================================================================
-Components: @bendyline/squisq@2.13.6
+Components: @bendyline/squisq@2.13.8
 Source files: node_modules/@bendyline/squisq/THIRD_PARTY_LICENSES.txt
 ==============================================================================
 THIRD-PARTY LICENSES FOR @bendyline/squisq

package/dist/{catalog-BQK05tne.d.ts → catalog-BmEXHaZf.d.ts}

@@ -1,5 +1,5 @@
 import { MarkdownDocument } from '@bendyline/squisq/markdown';
-import { C as CatalogSortOrder } from './settings-HrrCikVX.js';
+import { C as CatalogSortOrder } from './settings-C-TS15JZ.js';
 
 /**
  * Synchronous outside-in path layout.
@@ -36,8 +36,11 @@ declare function chooseOutsideInMarkdownPath(layout: OutsideInLayout, paths: rea
  *
  * Everything here is deterministic: identical inputs produce identical bytes
  * on every surface (shell, VS Code extension host, CLI). There are no
- * timestamps, no filesystem mtimes, and no locale-sensitive ordering, so a
- * catalog committed to git only changes when the documents do.
+ * filesystem mtimes and no locale-sensitive ordering. The only clock reading
+ * is a document's first-published and last-modified dates, carried forward from
+ * the previous catalog JSON and stamped only when a document first appears or
+ * its content changes — so a catalog committed to git still only changes when
+ * the documents do.
  */
 
 declare const CATALOG_GENERATOR = "docblocks-workspace-catalog";
@@ -65,11 +68,17 @@ interface CatalogEntry {
     readonly description?: string;
     readonly author?: string;
     readonly date?: string;
+    /** When the document first appeared in the catalog JSON (ISO 8601, UTC). */
+    readonly firstPublishedDate?: string;
+    /** When the catalog JSON last picked up a change to the document's content. */
+    readonly lastModifiedDate?: string;
     readonly tags?: readonly string[];
     readonly theme?: string;
     readonly outline: readonly CatalogOutlineEntry[];
     readonly wordCount: number;
     readonly excerpt?: string;
+    /** SHA-256 hex of the source text with normalized line endings; absent when unread. */
+    readonly contentHash?: string;
     /** Present only when the catalog is configured with `content: "markdown"`. */
     readonly markdown?: string;
 }
@@ -106,6 +115,23 @@ declare function createWorkspaceCatalog(title: string, entries: readonly Catalog
  */
 declare function serializeCatalogJson(catalog: WorkspaceCatalog): string;
 declare function isGeneratedCatalogJson(text: string): boolean;
+/** The dates a previously generated catalog recorded for one document. */
+interface CatalogDateRecord {
+    readonly firstPublishedDate: string;
+    readonly lastModifiedDate: string;
+    readonly contentHash?: string;
+}
+/**
+ * Per-path date history from a previously generated catalog JSON. Anything
+ * malformed is skipped, so the worst case is a document dated as new.
+ */
+declare function readCatalogDateHistory(text: string): Map<string, CatalogDateRecord>;
+/**
+ * Date each entry. A document keeps the dates `history` holds for its path;
+ * it is stamped `now` when it first appears, and its `lastModifiedDate`
+ * moves to `now` when its content hash changes.
+ */
+declare function stampCatalogDates(catalog: WorkspaceCatalog, history: ReadonlyMap<string, CatalogDateRecord>, now: Date): WorkspaceCatalog;
 /** Insert the generator marker directly after the doctype so it cannot affect quirks mode. */
 declare function stampCatalogHtml(html: string, inputsDigest: string): string;
 declare function readCatalogHtmlDigest(text: string): string | null;
@@ -119,4 +145,4 @@ declare function relativeCatalogLink(fromDirectory: string, toPath: string): str
  */
 declare function buildCatalogMarkdownDocument(catalog: WorkspaceCatalog, outputPath: string): MarkdownDocument;
 
-export { type CatalogEntry as C, OUTSIDE_IN_FORMAT_IDS as O, type WorkspaceCatalog as W, CATALOG_FORMAT_VERSION as a, CATALOG_GENERATOR as b, CATALOG_LIMITS as c, type CatalogDocumentFormat as d, type CatalogEntryHints as e, type CatalogOutlineEntry as f, type CatalogSource as g, type OutsideInFormatId as h, type OutsideInLayout as i, buildCatalogMarkdownDocument as j, catalogEntryForUnreadable as k, catalogEntryFromDocument as l, catalogEntryFromMarkdown as m, chooseOutsideInMarkdownPath as n, createWorkspaceCatalog as o, isGeneratedCatalogHtml as p, isGeneratedCatalogJson as q, readCatalogHtmlDigest as r, relativeCatalogLink as s, relocateOutsideInLayout as t, resolveOutsideInLayout as u, serializeCatalogJson as v, sortCatalogEntries as w, stampCatalogHtml as x };
+export { stampCatalogHtml as A, type CatalogEntry as C, OUTSIDE_IN_FORMAT_IDS as O, type WorkspaceCatalog as W, CATALOG_FORMAT_VERSION as a, CATALOG_GENERATOR as b, CATALOG_LIMITS as c, type CatalogDateRecord as d, type CatalogDocumentFormat as e, type CatalogEntryHints as f, type CatalogOutlineEntry as g, type CatalogSource as h, type OutsideInFormatId as i, type OutsideInLayout as j, buildCatalogMarkdownDocument as k, catalogEntryForUnreadable as l, catalogEntryFromDocument as m, catalogEntryFromMarkdown as n, chooseOutsideInMarkdownPath as o, createWorkspaceCatalog as p, isGeneratedCatalogHtml as q, isGeneratedCatalogJson as r, readCatalogDateHistory as s, readCatalogHtmlDigest as t, relativeCatalogLink as u, relocateOutsideInLayout as v, resolveOutsideInLayout as w, serializeCatalogJson as x, sortCatalogEntries as y, stampCatalogDates as z };

package/dist/{chunk-R2JX5N3F.js → chunk-L7HADBCQ.js}

@@ -168,11 +168,14 @@ function orderedEntry(entry) {
     "description",
     "author",
     "date",
+    "firstPublishedDate",
+    "lastModifiedDate",
     "tags",
     "theme",
     "outline",
     "wordCount",
     "excerpt",
+    "contentHash",
     "markdown"
   ];
   for (const key of keys) {
@@ -202,6 +205,50 @@ var CATALOG_JSON_MARKER = /^\uFEFF?\{\s*"generator"\s*:\s*"docblocks-workspace-c
 function isGeneratedCatalogJson(text) {
   return CATALOG_JSON_MARKER.test(text.slice(0, 256));
 }
+var CATALOG_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:\d{2}))?$/;
+var CONTENT_HASH_PATTERN = /^[0-9a-f]{64}$/;
+function catalogDate(value) {
+  return typeof value === "string" && CATALOG_DATE_PATTERN.test(value) && Number.isFinite(Date.parse(value)) ? value : void 0;
+}
+function readCatalogDateHistory(text) {
+  const history = /* @__PURE__ */ new Map();
+  if (!isGeneratedCatalogJson(text)) return history;
+  let parsed;
+  try {
+    parsed = JSON.parse(text.replace(/^\uFEFF/, ""));
+  } catch {
+    return history;
+  }
+  const documents = parsed?.documents;
+  if (!Array.isArray(documents)) return history;
+  for (const document of documents) {
+    if (!document || typeof document !== "object") continue;
+    const record = document;
+    const first = catalogDate(record.firstPublishedDate);
+    if (typeof record.path !== "string" || !first) continue;
+    const hash = record.contentHash;
+    history.set(record.path, {
+      firstPublishedDate: first,
+      lastModifiedDate: catalogDate(record.lastModifiedDate) ?? first,
+      ...typeof hash === "string" && CONTENT_HASH_PATTERN.test(hash) ? { contentHash: hash } : {}
+    });
+  }
+  return history;
+}
+function stampCatalogDates(catalog, history, now) {
+  const timestamp = now.toISOString().replace(/\.\d{3}Z$/, "Z");
+  return {
+    ...catalog,
+    documents: catalog.documents.map((entry) => {
+      const previous = history.get(entry.path);
+      return {
+        ...entry,
+        firstPublishedDate: previous?.firstPublishedDate ?? timestamp,
+        lastModifiedDate: previous && previous.contentHash === entry.contentHash ? previous.lastModifiedDate : timestamp
+      };
+    })
+  };
+}
 var CATALOG_HTML_MARKER = /<!-- docblocks-workspace-catalog v1 inputs=sha256:([0-9a-f]{64}) -->/;
 var CATALOG_HTML_MARKER_SCAN_CHARACTERS = 2048;
 function stampCatalogHtml(html, inputsDigest) {
@@ -369,6 +416,8 @@ export {
   createWorkspaceCatalog,
   serializeCatalogJson,
   isGeneratedCatalogJson,
+  readCatalogDateHistory,
+  stampCatalogDates,
   stampCatalogHtml,
   readCatalogHtmlDigest,
   isGeneratedCatalogHtml,

package/dist/{chunk-BC42VRYW.js → chunk-PQBUG5DY.js}

@@ -21,6 +21,7 @@ var WORKSPACE_SETTINGS_LIMITS = {
 var WORKSPACE_THEME_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
 var CATALOG_SORT_ORDERS = ["title", "path", "date"];
 var CATALOG_JSON_CONTENT_MODES = ["metadata", "markdown"];
+var WORKSPACE_OUTPUT_TEMPLATE_FORMATS = ["html"];
 var EMPTY_WORKSPACE_SETTINGS = Object.freeze({
   version: WORKSPACE_SETTINGS_VERSION
 });
@@ -85,6 +86,32 @@ function boundedPath(value, label) {
   if (!path) fail(`${label} must not be the workspace root.`);
   return path;
 }
+var OUTPUT_TEMPLATE_EXTENSIONS = {
+  html: [".html", ".htm"]
+};
+function validateOutputTemplatePath(value, format) {
+  const label = `documents.outputTemplates.${format}`;
+  const path = boundedPath(value, label);
+  const lower = path.toLowerCase();
+  if (!OUTPUT_TEMPLATE_EXTENSIONS[format].some((extension) => lower.endsWith(extension))) {
+    fail(`${label} must end with ${OUTPUT_TEMPLATE_EXTENSIONS[format].join(" or ")}.`);
+  }
+  return path;
+}
+function checkOutputTemplatePath(value, format) {
+  try {
+    return { ok: true, path: validateOutputTemplatePath(value, format) };
+  } catch (error) {
+    return { ok: false, message: shapeMessage(error) };
+  }
+}
+function parseOutputTemplates(value) {
+  if (value === void 0) return void 0;
+  const record = exactRecord(value, "documents.outputTemplates", WORKSPACE_OUTPUT_TEMPLATE_FORMATS);
+  return compact({
+    html: record.html === void 0 ? void 0 : validateOutputTemplatePath(record.html, "html")
+  });
+}
 var OUTPUT_EXTENSIONS = {
   html: [".html", ".htm"],
   json: [".json"]
@@ -146,6 +173,7 @@ function compact(value) {
   const entries = Object.entries(value).filter(([, field]) => field !== void 0);
   return entries.length > 0 ? Object.fromEntries(entries) : void 0;
 }
+var DOCUMENT_SETTINGS_KEYS = ["defaultTheme", "outputTemplates"];
 function parseWorkspaceSettings(value) {
   const root = isRecord(value) ? value : fail("Workspace settings must be a JSON object.");
   const version = root.version;
@@ -169,9 +197,10 @@ function parseWorkspaceSettings(value) {
   }
   let documents;
   if (root.documents !== void 0) {
-    const record = exactRecord(root.documents, "documents", ["defaultTheme"]);
+    const record = exactRecord(root.documents, "documents", DOCUMENT_SETTINGS_KEYS);
     documents = compact({
-      defaultTheme: optionalTheme(record.defaultTheme, "documents.defaultTheme")
+      defaultTheme: optionalTheme(record.defaultTheme, "documents.defaultTheme"),
+      outputTemplates: parseOutputTemplates(record.outputTemplates)
     });
   }
   let versionHistory;
@@ -278,7 +307,11 @@ function serializeWorkspaceSettings(settings) {
   if (normalized.$schema !== void 0) ordered.$schema = normalized.$schema;
   ordered.version = normalized.version;
   if (normalized.documents) {
-    ordered.documents = pick(normalized.documents, ["defaultTheme"]);
+    const { outputTemplates } = normalized.documents;
+    ordered.documents = {
+      ...pick(normalized.documents, ["defaultTheme"]),
+      ...outputTemplates ? { outputTemplates: pick(outputTemplates, WORKSPACE_OUTPUT_TEMPLATE_FORMATS) } : {}
+    };
   }
   if (normalized.versionHistory) {
     ordered.versionHistory = pick(normalized.versionHistory, ["enabled", "keep"]);
@@ -340,7 +373,7 @@ function optionalSection(key, value) {
 }
 function diffWorkspaceSettings(before, after) {
   const base = before ?? EMPTY_WORKSPACE_SETTINGS;
-  const documents = diffFields(base.documents, after.documents, ["defaultTheme"]);
+  const documents = diffFields(base.documents, after.documents, DOCUMENT_SETTINGS_KEYS);
   const versionHistory = diffFields(base.versionHistory, after.versionHistory, ["enabled", "keep"]);
   const top = diffFields(
     base.catalog,
@@ -378,12 +411,13 @@ function parseWorkspaceSettingsPatch(value) {
   const nullable = (field, parse) => field === null ? null : parse(field);
   const result = {};
   if (root.documents !== void 0) {
-    const record = exactRecord(root.documents, "documents", ["defaultTheme"]);
+    const record = exactRecord(root.documents, "documents", DOCUMENT_SETTINGS_KEYS);
     result.documents = compact({
       defaultTheme: nullable(
         record.defaultTheme,
         (input) => optionalTheme(input, "documents.defaultTheme")
-      )
+      ),
+      outputTemplates: nullable(record.outputTemplates, parseOutputTemplates)
     }) ?? {};
   }
   if (root.versionHistory !== void 0) {
@@ -451,11 +485,15 @@ function tryApplyWorkspaceSettingsPatch(base, patch) {
   }
 }
 function isDefaultWorkspaceSettings(settings) {
-  return settings?.documents?.defaultTheme === void 0 && settings?.versionHistory?.enabled === void 0 && settings?.versionHistory?.keep === void 0 && settings?.catalog?.html?.enabled !== true && settings?.catalog?.json?.enabled !== true;
+  return settings?.documents?.defaultTheme === void 0 && settings?.documents?.outputTemplates === void 0 && settings?.versionHistory?.enabled === void 0 && settings?.versionHistory?.keep === void 0 && settings?.catalog?.html?.enabled !== true && settings?.catalog?.json?.enabled !== true;
 }
 function resolveWorkspaceDefaultThemeId(settings) {
   return settings?.documents?.defaultTheme;
 }
+function resolveWorkspaceOutputTemplate(settings, format) {
+  const templates = settings?.documents?.outputTemplates;
+  return format === "html" ? templates?.html : void 0;
+}
 function resolveFallbackThemeId(frontmatterThemeId, settings) {
   if (frontmatterThemeId) return void 0;
   return resolveWorkspaceDefaultThemeId(settings);
@@ -494,7 +532,10 @@ export {
   WORKSPACE_THEME_ID_PATTERN,
   CATALOG_SORT_ORDERS,
   CATALOG_JSON_CONTENT_MODES,
+  WORKSPACE_OUTPUT_TEMPLATE_FORMATS,
   EMPTY_WORKSPACE_SETTINGS,
+  validateOutputTemplatePath,
+  checkOutputTemplatePath,
   validateCatalogOutputPath,
   checkCatalogOutputPath,
   parseWorkspaceSettings,
@@ -508,6 +549,7 @@ export {
   tryApplyWorkspaceSettingsPatch,
   isDefaultWorkspaceSettings,
   resolveWorkspaceDefaultThemeId,
+  resolveWorkspaceOutputTemplate,
   resolveFallbackThemeId,
   resolveWorkspaceVersioningEnabled,
   resolveCatalogOutputs

package/dist/{settings-HrrCikVX.d.ts → settings-C-TS15JZ.d.ts}

@@ -32,9 +32,22 @@ declare const CATALOG_SORT_ORDERS: readonly ["title", "path", "date"];
 type CatalogSortOrder = (typeof CATALOG_SORT_ORDERS)[number];
 declare const CATALOG_JSON_CONTENT_MODES: readonly ["metadata", "markdown"];
 type CatalogJsonContent = (typeof CATALOG_JSON_CONTENT_MODES)[number];
+/** Rendered formats a workspace can name a default page template for. */
+declare const WORKSPACE_OUTPUT_TEMPLATE_FORMATS: readonly ["html"];
+type WorkspaceOutputTemplateFormat = (typeof WORKSPACE_OUTPUT_TEMPLATE_FORMATS)[number];
+/** Workspace-relative page template path, by rendered output format. */
+type WorkspaceOutputTemplates = {
+    readonly [Format in WorkspaceOutputTemplateFormat]?: string;
+};
 interface WorkspaceDocumentSettings {
     /** Theme for documents whose frontmatter names none. */
     readonly defaultTheme?: string;
+    /**
+     * Page template for rendered documents whose frontmatter names none
+     * (`squisq-output-template`). A document's own choice, including `none`,
+     * always wins.
+     */
+    readonly outputTemplates?: WorkspaceOutputTemplates;
 }
 interface WorkspaceVersionHistorySettings {
     /** Absent inherits the app-wide preference. */
@@ -76,6 +89,16 @@ type WorkspaceSettingsParseResult = {
     readonly status: 'invalid' | 'unsupported-version';
     readonly message: string;
 };
+/** Validate a configured page template path for one rendered format. */
+declare function validateOutputTemplatePath(value: unknown, format: WorkspaceOutputTemplateFormat): WorkspacePath;
+/** Try-form for UI validation messages. */
+declare function checkOutputTemplatePath(value: unknown, format: WorkspaceOutputTemplateFormat): {
+    ok: true;
+    path: WorkspacePath;
+} | {
+    ok: false;
+    message: string;
+};
 type CatalogOutputKind = 'html' | 'json';
 /**
  * Validate a configured catalog output path. Outputs may never land inside
@@ -135,7 +158,8 @@ declare function tryApplyWorkspaceSettingsPatch(base: WorkspaceSettings | null,
 };
 /**
  * True when settings change nothing about how DocBlocks treats the folder: no
- * default theme, no version-history choice, and no catalog output turned on.
+ * default theme or page template, no version-history choice, and no catalog
+ * output turned on.
  * Fields that only configure a disabled output (a catalog title, path, order,
  * or page theme) are inert. Such settings are never worth creating a
  * `.docblocks/` folder for.
@@ -143,6 +167,8 @@ declare function tryApplyWorkspaceSettingsPatch(base: WorkspaceSettings | null,
 declare function isDefaultWorkspaceSettings(settings: WorkspaceSettings | null | undefined): boolean;
 /** The workspace default theme, or undefined to use the built-in default. */
 declare function resolveWorkspaceDefaultThemeId(settings: WorkspaceSettings | null | undefined): string | undefined;
+/** The workspace default page template for a rendered format, workspace-relative. */
+declare function resolveWorkspaceOutputTemplate(settings: WorkspaceSettings | null | undefined, format: string): string | undefined;
 /**
  * The theme a renderer should be told about explicitly. Every Squisq
  * exporter lets an explicit theme beat the document's own frontmatter, so a
@@ -167,4 +193,4 @@ interface ResolvedCatalogOutputs {
 /** Effective catalog configuration, or null when no output is enabled. */
 declare function resolveCatalogOutputs(settings: WorkspaceSettings | null | undefined): ResolvedCatalogOutputs | null;
 
-export { resolveCatalogOutputs as A, resolveFallbackThemeId as B, type CatalogSortOrder as C, DEFAULT_CATALOG_HTML_PATH as D, EMPTY_WORKSPACE_SETTINGS as E, resolveWorkspaceDefaultThemeId as F, resolveWorkspaceVersioningEnabled as G, serializeWorkspaceSettings as H, tryApplyWorkspaceSettingsPatch as I, validateCatalogOutputPath as J, type ResolvedCatalogOutputs as R, UnsupportedWorkspaceSettingsVersionError as U, type WorkspaceSettings as W, type WorkspaceSettingsPatch as a, CATALOG_JSON_CONTENT_MODES as b, CATALOG_SORT_ORDERS as c, type CatalogJsonContent as d, type CatalogOutputKind as e, DEFAULT_CATALOG_JSON_PATH as f, DEFAULT_CATALOG_TITLE as g, WORKSPACE_SETTINGS_DIRECTORY as h, WORKSPACE_SETTINGS_LIMITS as i, WORKSPACE_SETTINGS_PATH as j, WORKSPACE_SETTINGS_VERSION as k, WORKSPACE_THEME_ID_PATTERN as l, type WorkspaceCatalogHtmlSettings as m, type WorkspaceCatalogJsonSettings as n, type WorkspaceCatalogSettings as o, type WorkspaceDocumentSettings as p, type WorkspaceSettingsParseResult as q, type WorkspaceVersionHistorySettings as r, applyWorkspaceSettingsPatch as s, checkCatalogOutputPath as t, diffWorkspaceSettings as u, isDefaultWorkspaceSettings as v, isEmptyWorkspaceSettingsPatch as w, parseWorkspaceSettings as x, parseWorkspaceSettingsPatch as y, parseWorkspaceSettingsText as z };
+export { isEmptyWorkspaceSettingsPatch as A, parseWorkspaceSettings as B, type CatalogSortOrder as C, DEFAULT_CATALOG_HTML_PATH as D, EMPTY_WORKSPACE_SETTINGS as E, parseWorkspaceSettingsPatch as F, parseWorkspaceSettingsText as G, resolveCatalogOutputs as H, resolveFallbackThemeId as I, resolveWorkspaceDefaultThemeId as J, resolveWorkspaceOutputTemplate as K, resolveWorkspaceVersioningEnabled as L, serializeWorkspaceSettings as M, tryApplyWorkspaceSettingsPatch as N, validateCatalogOutputPath as O, validateOutputTemplatePath as P, type ResolvedCatalogOutputs as R, UnsupportedWorkspaceSettingsVersionError as U, type WorkspaceSettings as W, type WorkspaceSettingsPatch as a, CATALOG_JSON_CONTENT_MODES as b, CATALOG_SORT_ORDERS as c, type CatalogJsonContent as d, type CatalogOutputKind as e, DEFAULT_CATALOG_JSON_PATH as f, DEFAULT_CATALOG_TITLE as g, WORKSPACE_OUTPUT_TEMPLATE_FORMATS as h, WORKSPACE_SETTINGS_DIRECTORY as i, WORKSPACE_SETTINGS_LIMITS as j, WORKSPACE_SETTINGS_PATH as k, WORKSPACE_SETTINGS_VERSION as l, WORKSPACE_THEME_ID_PATTERN as m, type WorkspaceCatalogHtmlSettings as n, type WorkspaceCatalogJsonSettings as o, type WorkspaceCatalogSettings as p, type WorkspaceDocumentSettings as q, type WorkspaceOutputTemplateFormat as r, type WorkspaceOutputTemplates as s, type WorkspaceSettingsParseResult as t, type WorkspaceVersionHistorySettings as u, applyWorkspaceSettingsPatch as v, checkCatalogOutputPath as w, checkOutputTemplatePath as x, diffWorkspaceSettings as y, isDefaultWorkspaceSettings as z };

package/dist/vscode/index.d.ts

@@ -1,4 +1,4 @@
-import { W as WorkspaceSettings, a as WorkspaceSettingsPatch } from '../settings-HrrCikVX.js';
+import { W as WorkspaceSettings, a as WorkspaceSettingsPatch } from '../settings-C-TS15JZ.js';
 import '../workspace-path-CWVrcuPL.js';
 
 /**

package/dist/vscode/index.js

@@ -1,7 +1,7 @@
 import {
   parseWorkspaceSettings,
   parseWorkspaceSettingsPatch
-} from "../chunk-BC42VRYW.js";
+} from "../chunk-PQBUG5DY.js";
 import {
   HOST_WIRE_LIMITS,
   isBoundedString

package/dist/workspace-index/index.d.ts

@@ -1,8 +1,8 @@
 import { o as FileSystemProviderV2, n as FileSystemProviderCapabilities } from '../v2-DwxWjFC0.js';
 import { a as WorkspacePath } from '../workspace-path-CWVrcuPL.js';
-import { d as CatalogDocumentFormat, f as CatalogOutlineEntry } from '../catalog-BQK05tne.js';
+import { e as CatalogDocumentFormat, g as CatalogOutlineEntry } from '../catalog-BmEXHaZf.js';
 import '@bendyline/squisq/markdown';
-import '../settings-HrrCikVX.js';
+import '../settings-C-TS15JZ.js';
 
 /**
  * What the index reads from. Only read methods are reachable, so the index

package/dist/workspace-index/index.js

@@ -3,7 +3,7 @@ import {
   chooseOutsideInMarkdownPath,
   normalizeLineEndings,
   resolveOutsideInLayout
-} from "../chunk-R2JX5N3F.js";
+} from "../chunk-L7HADBCQ.js";
 import {
   isCompanionDirectoryName,
   isDiscoverableWorkspaceEntry,

package/dist/workspace-settings/index.d.ts

@@ -1,7 +1,7 @@
-import { R as ResolvedCatalogOutputs, W as WorkspaceSettings, a as WorkspaceSettingsPatch } from '../settings-HrrCikVX.js';
-export { b as CATALOG_JSON_CONTENT_MODES, c as CATALOG_SORT_ORDERS, d as CatalogJsonContent, e as CatalogOutputKind, C as CatalogSortOrder, D as DEFAULT_CATALOG_HTML_PATH, f as DEFAULT_CATALOG_JSON_PATH, g as DEFAULT_CATALOG_TITLE, E as EMPTY_WORKSPACE_SETTINGS, U as UnsupportedWorkspaceSettingsVersionError, h as WORKSPACE_SETTINGS_DIRECTORY, i as WORKSPACE_SETTINGS_LIMITS, j as WORKSPACE_SETTINGS_PATH, k as WORKSPACE_SETTINGS_VERSION, l as WORKSPACE_THEME_ID_PATTERN, m as WorkspaceCatalogHtmlSettings, n as WorkspaceCatalogJsonSettings, o as WorkspaceCatalogSettings, p as WorkspaceDocumentSettings, q as WorkspaceSettingsParseResult, r as WorkspaceVersionHistorySettings, s as applyWorkspaceSettingsPatch, t as checkCatalogOutputPath, u as diffWorkspaceSettings, v as isDefaultWorkspaceSettings, w as isEmptyWorkspaceSettingsPatch, x as parseWorkspaceSettings, y as parseWorkspaceSettingsPatch, z as parseWorkspaceSettingsText, A as resolveCatalogOutputs, B as resolveFallbackThemeId, F as resolveWorkspaceDefaultThemeId, G as resolveWorkspaceVersioningEnabled, H as serializeWorkspaceSettings, I as tryApplyWorkspaceSettingsPatch, J as validateCatalogOutputPath } from '../settings-HrrCikVX.js';
-import { C as CatalogEntry, W as WorkspaceCatalog } from '../catalog-BQK05tne.js';
-export { a as CATALOG_FORMAT_VERSION, b as CATALOG_GENERATOR, c as CATALOG_LIMITS, d as CatalogDocumentFormat, e as CatalogEntryHints, f as CatalogOutlineEntry, g as CatalogSource, O as OUTSIDE_IN_FORMAT_IDS, h as OutsideInFormatId, i as OutsideInLayout, j as buildCatalogMarkdownDocument, k as catalogEntryForUnreadable, l as catalogEntryFromDocument, m as catalogEntryFromMarkdown, n as chooseOutsideInMarkdownPath, o as createWorkspaceCatalog, p as isGeneratedCatalogHtml, q as isGeneratedCatalogJson, r as readCatalogHtmlDigest, s as relativeCatalogLink, t as relocateOutsideInLayout, u as resolveOutsideInLayout, v as serializeCatalogJson, w as sortCatalogEntries, x as stampCatalogHtml } from '../catalog-BQK05tne.js';
+import { R as ResolvedCatalogOutputs, W as WorkspaceSettings, a as WorkspaceSettingsPatch } from '../settings-C-TS15JZ.js';
+export { b as CATALOG_JSON_CONTENT_MODES, c as CATALOG_SORT_ORDERS, d as CatalogJsonContent, e as CatalogOutputKind, C as CatalogSortOrder, D as DEFAULT_CATALOG_HTML_PATH, f as DEFAULT_CATALOG_JSON_PATH, g as DEFAULT_CATALOG_TITLE, E as EMPTY_WORKSPACE_SETTINGS, U as UnsupportedWorkspaceSettingsVersionError, h as WORKSPACE_OUTPUT_TEMPLATE_FORMATS, i as WORKSPACE_SETTINGS_DIRECTORY, j as WORKSPACE_SETTINGS_LIMITS, k as WORKSPACE_SETTINGS_PATH, l as WORKSPACE_SETTINGS_VERSION, m as WORKSPACE_THEME_ID_PATTERN, n as WorkspaceCatalogHtmlSettings, o as WorkspaceCatalogJsonSettings, p as WorkspaceCatalogSettings, q as WorkspaceDocumentSettings, r as WorkspaceOutputTemplateFormat, s as WorkspaceOutputTemplates, t as WorkspaceSettingsParseResult, u as WorkspaceVersionHistorySettings, v as applyWorkspaceSettingsPatch, w as checkCatalogOutputPath, x as checkOutputTemplatePath, y as diffWorkspaceSettings, z as isDefaultWorkspaceSettings, A as isEmptyWorkspaceSettingsPatch, B as parseWorkspaceSettings, F as parseWorkspaceSettingsPatch, G as parseWorkspaceSettingsText, H as resolveCatalogOutputs, I as resolveFallbackThemeId, J as resolveWorkspaceDefaultThemeId, K as resolveWorkspaceOutputTemplate, L as resolveWorkspaceVersioningEnabled, M as serializeWorkspaceSettings, N as tryApplyWorkspaceSettingsPatch, O as validateCatalogOutputPath, P as validateOutputTemplatePath } from '../settings-C-TS15JZ.js';
+import { C as CatalogEntry, W as WorkspaceCatalog } from '../catalog-BmEXHaZf.js';
+export { a as CATALOG_FORMAT_VERSION, b as CATALOG_GENERATOR, c as CATALOG_LIMITS, d as CatalogDateRecord, e as CatalogDocumentFormat, f as CatalogEntryHints, g as CatalogOutlineEntry, h as CatalogSource, O as OUTSIDE_IN_FORMAT_IDS, i as OutsideInFormatId, j as OutsideInLayout, k as buildCatalogMarkdownDocument, l as catalogEntryForUnreadable, m as catalogEntryFromDocument, n as catalogEntryFromMarkdown, o as chooseOutsideInMarkdownPath, p as createWorkspaceCatalog, q as isGeneratedCatalogHtml, r as isGeneratedCatalogJson, s as readCatalogDateHistory, t as readCatalogHtmlDigest, u as relativeCatalogLink, v as relocateOutsideInLayout, w as resolveOutsideInLayout, x as serializeCatalogJson, y as sortCatalogEntries, z as stampCatalogDates, A as stampCatalogHtml } from '../catalog-BmEXHaZf.js';
 import { MarkdownDocument } from '@bendyline/squisq/markdown';
 import { v as FileSystemVersion, o as FileSystemProviderV2 } from '../v2-DwxWjFC0.js';
 import { a as WorkspacePath } from '../workspace-path-CWVrcuPL.js';
@@ -37,6 +37,20 @@ declare const WORKSPACE_SETTINGS_JSON_SCHEMA: {
                     readonly type: "string";
                     readonly pattern: string;
                 };
+                readonly outputTemplates: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly description: "Page templates for rendered documents whose frontmatter names none (squisq-output-template). A document’s own choice, including \"none\", always wins.";
+                    readonly properties: {
+                        readonly html: {
+                            readonly pattern: "\\.html?$";
+                            readonly description: "Workspace-relative HTML page template for Web pages, such as \"_templates/post.html\". Its unnamed <slot> receives the page content.";
+                            readonly type: "string";
+                            readonly minLength: 1;
+                            readonly maxLength: 1024;
+                        };
+                    };
+                };
             };
         };
         readonly versionHistory: {
@@ -154,6 +168,11 @@ interface WorkspaceOutputsRenderer {
     }): string | Promise<string>;
     /** Parse rendered HTML that has no Markdown companion yet. Optional. */
     importHtml?(html: string): MarkdownDocument | Promise<MarkdownDocument>;
+    /**
+     * True for an HTML page template — the chrome other pages are generated
+     * through, not a document of its own — which the catalog leaves out. Optional.
+     */
+    isPageTemplate?(html: string): boolean;
 }
 declare const WORKSPACE_OUTPUT_LIMITS: {
     readonly maxDocuments: 5000;
@@ -188,6 +207,8 @@ interface RefreshWorkspaceOutputsOptions {
     /** Compute everything, write nothing. */
     readonly dryRun?: boolean;
     readonly limits?: Partial<WorkspaceOutputLimits>;
+    /** Time stamped on new or changed documents in the catalog JSON. Defaults to now. */
+    readonly now?: Date;
 }
 type WorkspaceOutputStatus = 'written' | 'unchanged' | 'blocked' | 'would-write';
 interface WorkspaceOutputResult {
@@ -211,7 +232,7 @@ declare function isCatalogRelevantPath(path: string, settings: WorkspaceSettings
 /** True for the workspace settings directory or anything inside it. */
 declare function isWorkspaceSettingsPath(path: string): boolean;
 /** Walk the workspace and build its catalog without writing anything. */
-declare function collectWorkspaceCatalog(io: WorkspaceOutputsIO, resolved: ResolvedCatalogOutputs, renderer: Pick<WorkspaceOutputsRenderer, 'importHtml'>, options?: Omit<RefreshWorkspaceOutputsOptions, 'force' | 'dryRun'>): Promise<WorkspaceCatalog>;
+declare function collectWorkspaceCatalog(io: WorkspaceOutputsIO, resolved: ResolvedCatalogOutputs, renderer: Pick<WorkspaceOutputsRenderer, 'importHtml' | 'isPageTemplate'>, options?: Omit<RefreshWorkspaceOutputsOptions, 'force' | 'dryRun' | 'now'>): Promise<WorkspaceCatalog>;
 /**
  * Regenerate every enabled catalog output for one workspace. Throws
  * {@link WorkspaceOutputsLimitError} when over budget, `FsError('aborted')`

package/dist/workspace-settings/index.js

@@ -11,6 +11,8 @@ import {
   createWorkspaceCatalog,
   isGeneratedCatalogHtml,
   isGeneratedCatalogJson,
+  normalizeLineEndings,
+  readCatalogDateHistory,
   readCatalogHtmlDigest,
   relativeCatalogLink,
   relocateOutsideInLayout,
@@ -18,8 +20,9 @@ import {
   serializeCatalogJson,
   sha256Hex,
   sortCatalogEntries,
+  stampCatalogDates,
   stampCatalogHtml
-} from "../chunk-R2JX5N3F.js";
+} from "../chunk-L7HADBCQ.js";
 import {
   CATALOG_JSON_CONTENT_MODES,
   CATALOG_SORT_ORDERS,
@@ -28,6 +31,7 @@ import {
   DEFAULT_CATALOG_TITLE,
   EMPTY_WORKSPACE_SETTINGS,
   UnsupportedWorkspaceSettingsVersionError,
+  WORKSPACE_OUTPUT_TEMPLATE_FORMATS,
   WORKSPACE_SETTINGS_DIRECTORY,
   WORKSPACE_SETTINGS_LIMITS,
   WORKSPACE_SETTINGS_PATH,
@@ -35,6 +39,7 @@ import {
   WORKSPACE_THEME_ID_PATTERN,
   applyWorkspaceSettingsPatch,
   checkCatalogOutputPath,
+  checkOutputTemplatePath,
   diffWorkspaceSettings,
   isDefaultWorkspaceSettings,
   isEmptyWorkspaceSettingsPatch,
@@ -44,11 +49,13 @@ import {
   resolveCatalogOutputs,
   resolveFallbackThemeId,
   resolveWorkspaceDefaultThemeId,
+  resolveWorkspaceOutputTemplate,
   resolveWorkspaceVersioningEnabled,
   serializeWorkspaceSettings,
   tryApplyWorkspaceSettingsPatch,
-  validateCatalogOutputPath
-} from "../chunk-BC42VRYW.js";
+  validateCatalogOutputPath,
+  validateOutputTemplatePath
+} from "../chunk-PQBUG5DY.js";
 import {
   SQUISQ_RUNTIME_DIRECTORY_NAME,
   isDiscoverableWorkspaceEntry,
@@ -92,6 +99,18 @@ var WORKSPACE_SETTINGS_JSON_SCHEMA = {
         defaultTheme: {
           ...themeId,
           description: "Theme for documents whose frontmatter does not name one. A document\u2019s own theme always wins."
+        },
+        outputTemplates: {
+          type: "object",
+          additionalProperties: false,
+          description: 'Page templates for rendered documents whose frontmatter names none (squisq-output-template). A document\u2019s own choice, including "none", always wins.',
+          properties: {
+            html: {
+              ...relativePath,
+              pattern: "\\.html?$",
+              description: 'Workspace-relative HTML page template for Web pages, such as "_templates/post.html". Its unnamed <slot> receives the page content.'
+            }
+          }
         }
       }
     },
@@ -351,7 +370,7 @@ async function collectWorkspaceCatalog(io, resolved, renderer, options = {}) {
       const text = new TextDecoder("utf-8").decode(read.data);
       if (target.mode === "markdown") {
         entry = await catalogEntryFromMarkdown(target.source, text, { includeMarkdown });
-      } else if (isGeneratedCatalogHtml(text)) {
+      } else if (isGeneratedCatalogHtml(text) || renderer.isPageTemplate?.(text)) {
         entry = null;
       } else if (renderer.importHtml) {
         const head = text.slice(0, 64 * 1024);
@@ -362,6 +381,7 @@ async function collectWorkspaceCatalog(io, resolved, renderer, options = {}) {
       } else {
         entry = catalogEntryForUnreadable(target.source);
       }
+      if (entry) entry = { ...entry, contentHash: await sha256Hex(normalizeLineEndings(text)) };
     }
     cache?.set(target.source.path, {
       readPath: target.readPath,
@@ -426,7 +446,9 @@ async function writeOutput(io, request, limits, options) {
       return blocked(`${path} is an edited document. Choose another catalog path.`);
     }
   }
-  const bytes = new TextEncoder().encode(await request.produce());
+  const bytes = new TextEncoder().encode(
+    await request.produce(existing ? new TextDecoder("utf-8").decode(existing.data) : null)
+  );
   if (bytes.byteLength > limits.maxOutputBytes) {
     return blocked(
       `The catalog would exceed ${Math.round(limits.maxOutputBytes / 1024 / 1024)} MiB and was not written.`
@@ -451,13 +473,20 @@ async function refreshWorkspaceOutputs(io, settings, renderer, options = {}) {
   if (resolved.json) {
     throwIfAborted(options.signal);
     const content = resolved.json.content;
+    const now = options.now ?? /* @__PURE__ */ new Date();
     outputs.push(
       await writeOutput(
         io,
         {
           kind: "json",
           path: resolved.json.path,
-          produce: async () => serializeCatalogJson(content === "markdown" ? catalog : metadataCatalog)
+          produce: async (previous) => serializeCatalogJson(
+            stampCatalogDates(
+              content === "markdown" ? catalog : metadataCatalog,
+              readCatalogDateHistory(previous ?? ""),
+              now
+            )
+          )
         },
         limits,
         options
@@ -771,6 +800,7 @@ export {
   WORKSPACE_OUTPUTS_DEBOUNCE_MS,
   WORKSPACE_OUTPUTS_MAX_WAIT_MS,
   WORKSPACE_OUTPUT_LIMITS,
+  WORKSPACE_OUTPUT_TEMPLATE_FORMATS,
   WORKSPACE_SETTINGS_DIRECTORY,
   WORKSPACE_SETTINGS_JSON_SCHEMA,
   WORKSPACE_SETTINGS_LIMITS,
@@ -784,6 +814,7 @@ export {
   catalogEntryFromDocument,
   catalogEntryFromMarkdown,
   checkCatalogOutputPath,
+  checkOutputTemplatePath,
   chooseOutsideInMarkdownPath,
   collectWorkspaceCatalog,
   createWorkspaceCatalog,
@@ -800,6 +831,7 @@ export {
   parseWorkspaceSettings,
   parseWorkspaceSettingsPatch,
   parseWorkspaceSettingsText,
+  readCatalogDateHistory,
   readCatalogHtmlDigest,
   readWorkspaceSettings,
   refreshWorkspaceOutputs,
@@ -809,12 +841,15 @@ export {
   resolveFallbackThemeId,
   resolveOutsideInLayout,
   resolveWorkspaceDefaultThemeId,
+  resolveWorkspaceOutputTemplate,
   resolveWorkspaceVersioningEnabled,
   saveWorkspaceSettingsPatch,
   serializeCatalogJson,
   serializeWorkspaceSettings,
   sortCatalogEntries,
+  stampCatalogDates,
   stampCatalogHtml,
   tryApplyWorkspaceSettingsPatch,
-  validateCatalogOutputPath
+  validateCatalogOutputPath,
+  validateOutputTemplatePath
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/docblocks",
-  "version": "2.7.8",
+  "version": "2.7.9",
   "description": "Core data structures and filesystem abstractions for DocBlocks",
   "license": "MIT",
   "author": "Bendyline",
@@ -126,7 +126,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@bendyline/squisq": "2.13.6",
+    "@bendyline/squisq": "2.13.8",
     "zod": "3.25.76"
   }
 }