@ctcstack/ctcdocs-core 0.22.0 → 0.22.1

package/dist/document-format.d.ts

@@ -0,0 +1,42 @@
+/**
+ * What a published page is made from, said once for the sync, the site and
+ * the Worker: a Google Doc, a PDF file (ADR-027), a spreadsheet (ADR-046), or
+ * a video or audio file (ADR-047).
+ *
+ * The same fact travels under three names. The page's frontmatter records its
+ * `sourceType`, the generated index and a run's report its format, and the
+ * MCP server its own `format`, which calls a Google Doc `doc` (ADR-044). Each
+ * is derived here from the format, so a new kind of page is added in one
+ * place and every list that names the kinds follows.
+ */
+/** The kinds of page a Drive file is published as. */
+export declare const DOCUMENT_FORMATS: readonly ["google-doc", "pdf", "sheet", "video", "audio"];
+export type DocumentFormat = (typeof DOCUMENT_FORMATS)[number];
+/**
+ * The frontmatter `sourceType` of a page published from a Drive file. A video
+ * and an audio file share one; the page's `media.kind` tells them apart.
+ */
+export declare const DOCUMENT_SOURCE_TYPES: readonly ["google-doc", "drive-pdf", "drive-sheet", "drive-media"];
+export type DocumentSourceType = (typeof DOCUMENT_SOURCE_TYPES)[number];
+/** The `sourceType` a page of `format` records. */
+export declare function documentSourceType(format: DocumentFormat): DocumentSourceType;
+/** Whether a page's `sourceType` says it was published from a Drive file. */
+export declare function isDocumentSourceType(value: string | undefined): value is DocumentSourceType;
+/**
+ * The format of a page, from its `sourceType` and, for a recording, the kind
+ * its frontmatter records; `undefined` for a page no Drive file made.
+ */
+export declare function documentFormatOf(sourceType: string | undefined, mediaKind?: 'video' | 'audio'): DocumentFormat | undefined;
+/**
+ * The mark beside a page that is not a Google Doc, in the sidebar and in a
+ * run's list of pages.
+ */
+export declare const DOCUMENT_FORMAT_BADGES: Readonly<Record<DocumentFormat, string | undefined>>;
+/**
+ * How `llms.txt` names a page that is not a Google Doc after its title, as in
+ * `Price list (spreadsheet)`.
+ */
+export declare const DOCUMENT_FORMAT_NOUNS: Readonly<Record<DocumentFormat, string | undefined>>;
+/** The format the MCP server reports: a Google Doc is `doc` (ADR-044). */
+export type AgentDocumentFormat = Exclude<DocumentFormat, 'google-doc'> | 'doc';
+export declare function agentDocumentFormat(format: DocumentFormat): AgentDocumentFormat;

package/dist/document-format.js

@@ -0,0 +1,87 @@
+/**
+ * What a published page is made from, said once for the sync, the site and
+ * the Worker: a Google Doc, a PDF file (ADR-027), a spreadsheet (ADR-046), or
+ * a video or audio file (ADR-047).
+ *
+ * The same fact travels under three names. The page's frontmatter records its
+ * `sourceType`, the generated index and a run's report its format, and the
+ * MCP server its own `format`, which calls a Google Doc `doc` (ADR-044). Each
+ * is derived here from the format, so a new kind of page is added in one
+ * place and every list that names the kinds follows.
+ */
+/** The kinds of page a Drive file is published as. */
+export const DOCUMENT_FORMATS = [
+    'google-doc',
+    'pdf',
+    'sheet',
+    'video',
+    'audio',
+];
+/**
+ * The frontmatter `sourceType` of a page published from a Drive file. A video
+ * and an audio file share one; the page's `media.kind` tells them apart.
+ */
+export const DOCUMENT_SOURCE_TYPES = [
+    'google-doc',
+    'drive-pdf',
+    'drive-sheet',
+    'drive-media',
+];
+const SOURCE_TYPES = {
+    'google-doc': 'google-doc',
+    pdf: 'drive-pdf',
+    sheet: 'drive-sheet',
+    video: 'drive-media',
+    audio: 'drive-media',
+};
+/** The `sourceType` a page of `format` records. */
+export function documentSourceType(format) {
+    return SOURCE_TYPES[format];
+}
+/** Whether a page's `sourceType` says it was published from a Drive file. */
+export function isDocumentSourceType(value) {
+    return DOCUMENT_SOURCE_TYPES.includes(value);
+}
+/**
+ * The format of a page, from its `sourceType` and, for a recording, the kind
+ * its frontmatter records; `undefined` for a page no Drive file made.
+ */
+export function documentFormatOf(sourceType, mediaKind) {
+    switch (sourceType) {
+        case 'google-doc':
+            return 'google-doc';
+        case 'drive-pdf':
+            return 'pdf';
+        case 'drive-sheet':
+            return 'sheet';
+        case 'drive-media':
+            return mediaKind;
+        default:
+            return undefined;
+    }
+}
+/**
+ * The mark beside a page that is not a Google Doc, in the sidebar and in a
+ * run's list of pages.
+ */
+export const DOCUMENT_FORMAT_BADGES = {
+    'google-doc': undefined,
+    pdf: 'PDF',
+    sheet: 'Sheet',
+    video: 'Video',
+    audio: 'Audio',
+};
+/**
+ * How `llms.txt` names a page that is not a Google Doc after its title, as in
+ * `Price list (spreadsheet)`.
+ */
+export const DOCUMENT_FORMAT_NOUNS = {
+    'google-doc': undefined,
+    pdf: 'PDF',
+    sheet: 'spreadsheet',
+    video: 'video',
+    audio: 'audio',
+};
+export function agentDocumentFormat(format) {
+    return format === 'google-doc' ? 'doc' : format;
+}

package/dist/index.d.ts

@@ -12,3 +12,5 @@ export { accessFindings } from './access-findings.js';
 export type { AccessFinding } from './access-findings.js';
 export { fetchCharacterLimit, loadSiteConfiguration, MCP_DEFAULTS, parseSiteConfiguration, SiteConfigurationError, } from './site-configuration.js';
 export type { AddressPolicy, BrandConfiguration, DeploymentConfiguration, DeploymentEnvironmentConfiguration, DeploymentEnvironmentConfigurations, DeploymentVisibility, HomeConfiguration, McpConfiguration, McpRecentConfiguration, McpSearchConfiguration, NavigationConfiguration, SignInConfiguration, SiteConfiguration, SyncConfigurationDefaults, } from './site-configuration.js';
+export { agentDocumentFormat, DOCUMENT_FORMAT_BADGES, DOCUMENT_FORMAT_NOUNS, DOCUMENT_FORMATS, DOCUMENT_SOURCE_TYPES, documentFormatOf, documentSourceType, isDocumentSourceType, } from './document-format.js';
+export type { AgentDocumentFormat, DocumentFormat, DocumentSourceType, } from './document-format.js';

package/dist/index.js

@@ -7,3 +7,4 @@ export { CorpusStructureError, EMPTY_CORPUS, parseCorpusStructure, readCorpusStr
 export { ADMINS_CLASS, chainReaders, chainRules, classIdentifiers, computeAccessModel, documentClass, folderChain, folderClass, intersectReaders, MEMBERS_CLASS, nextPublishedReaders, widensReaders, } from './access-classes.js';
 export { accessFindings } from './access-findings.js';
 export { fetchCharacterLimit, loadSiteConfiguration, MCP_DEFAULTS, parseSiteConfiguration, SiteConfigurationError, } from './site-configuration.js';
+export { agentDocumentFormat, DOCUMENT_FORMAT_BADGES, DOCUMENT_FORMAT_NOUNS, DOCUMENT_FORMATS, DOCUMENT_SOURCE_TYPES, documentFormatOf, documentSourceType, isDocumentSourceType, } from './document-format.js';

package/dist/site-configuration.d.ts

@@ -6,8 +6,17 @@ export interface BrandConfiguration {
     readonly siteTitle: string;
     /** One sentence, used as the site-wide meta description. */
     readonly siteDescription: string;
-    /** Site-root-relative path of the favicon served from `public/`. */
+    /**
+     * Site-root-relative path of the favicon served from `public/`, which is
+     * also the mark in the header.
+     */
     readonly faviconPath: string;
+    /**
+     * The same mark drawn for a dark ground, when the light one would not show
+     * on it: the header shows it under the dark theme, and a browser whose
+     * interface is dark shows it in the tab.
+     */
+    readonly faviconDarkPath?: string;
 }
 export interface HomeConfiguration {
     /**

package/dist/site-configuration.js

@@ -333,8 +333,15 @@ export function parseSiteConfiguration(input) {
     if (!faviconPath.startsWith('/')) {
         fail('brand.faviconPath', 'must be a site-root-relative path');
     }
+    const faviconDarkPath = brandSource.faviconDarkPath === undefined
+        ? undefined
+        : text(brandSource, 'faviconDarkPath', 'brand.faviconDarkPath');
+    if (faviconDarkPath !== undefined && !faviconDarkPath.startsWith('/')) {
+        fail('brand.faviconDarkPath', 'must be a site-root-relative path');
+    }
     const brand = {
         faviconPath,
+        ...(faviconDarkPath === undefined ? {} : { faviconDarkPath }),
         name: text(brandSource, 'name', 'brand.name'),
         siteDescription: text(brandSource, 'siteDescription', 'brand.siteDescription'),
         siteTitle: text(brandSource, 'siteTitle', 'brand.siteTitle'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctcstack/ctcdocs-core",
-  "version": "0.22.0",
+  "version": "0.22.1",
   "description": "Configuration schema, project layout, generated-path allowlist and the published Markdown form shared by the CTCDocs platform packages.",
   "keywords": [
     "ctcdocs",
@@ -31,6 +31,10 @@
     "./published-markdown": {
       "types": "./dist/published-markdown.d.ts",
       "default": "./dist/published-markdown.js"
+    },
+    "./document-format": {
+      "types": "./dist/document-format.d.ts",
+      "default": "./dist/document-format.js"
     }
   },
   "files": [

package/src/document-format.ts

@@ -0,0 +1,116 @@
+/**
+ * What a published page is made from, said once for the sync, the site and
+ * the Worker: a Google Doc, a PDF file (ADR-027), a spreadsheet (ADR-046), or
+ * a video or audio file (ADR-047).
+ *
+ * The same fact travels under three names. The page's frontmatter records its
+ * `sourceType`, the generated index and a run's report its format, and the
+ * MCP server its own `format`, which calls a Google Doc `doc` (ADR-044). Each
+ * is derived here from the format, so a new kind of page is added in one
+ * place and every list that names the kinds follows.
+ */
+
+/** The kinds of page a Drive file is published as. */
+export const DOCUMENT_FORMATS = [
+  'google-doc',
+  'pdf',
+  'sheet',
+  'video',
+  'audio',
+] as const;
+
+export type DocumentFormat = (typeof DOCUMENT_FORMATS)[number];
+
+/**
+ * The frontmatter `sourceType` of a page published from a Drive file. A video
+ * and an audio file share one; the page's `media.kind` tells them apart.
+ */
+export const DOCUMENT_SOURCE_TYPES = [
+  'google-doc',
+  'drive-pdf',
+  'drive-sheet',
+  'drive-media',
+] as const;
+
+export type DocumentSourceType = (typeof DOCUMENT_SOURCE_TYPES)[number];
+
+const SOURCE_TYPES: Readonly<Record<DocumentFormat, DocumentSourceType>> = {
+  'google-doc': 'google-doc',
+  pdf: 'drive-pdf',
+  sheet: 'drive-sheet',
+  video: 'drive-media',
+  audio: 'drive-media',
+};
+
+/** The `sourceType` a page of `format` records. */
+export function documentSourceType(format: DocumentFormat): DocumentSourceType {
+  return SOURCE_TYPES[format];
+}
+
+/** Whether a page's `sourceType` says it was published from a Drive file. */
+export function isDocumentSourceType(
+  value: string | undefined,
+): value is DocumentSourceType {
+  return (DOCUMENT_SOURCE_TYPES as readonly (string | undefined)[]).includes(
+    value,
+  );
+}
+
+/**
+ * The format of a page, from its `sourceType` and, for a recording, the kind
+ * its frontmatter records; `undefined` for a page no Drive file made.
+ */
+export function documentFormatOf(
+  sourceType: string | undefined,
+  mediaKind?: 'video' | 'audio',
+): DocumentFormat | undefined {
+  switch (sourceType) {
+    case 'google-doc':
+      return 'google-doc';
+    case 'drive-pdf':
+      return 'pdf';
+    case 'drive-sheet':
+      return 'sheet';
+    case 'drive-media':
+      return mediaKind;
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * The mark beside a page that is not a Google Doc, in the sidebar and in a
+ * run's list of pages.
+ */
+export const DOCUMENT_FORMAT_BADGES: Readonly<
+  Record<DocumentFormat, string | undefined>
+> = {
+  'google-doc': undefined,
+  pdf: 'PDF',
+  sheet: 'Sheet',
+  video: 'Video',
+  audio: 'Audio',
+};
+
+/**
+ * How `llms.txt` names a page that is not a Google Doc after its title, as in
+ * `Price list (spreadsheet)`.
+ */
+export const DOCUMENT_FORMAT_NOUNS: Readonly<
+  Record<DocumentFormat, string | undefined>
+> = {
+  'google-doc': undefined,
+  pdf: 'PDF',
+  sheet: 'spreadsheet',
+  video: 'video',
+  audio: 'audio',
+};
+
+/** The format the MCP server reports: a Google Doc is `doc` (ADR-044). */
+export type AgentDocumentFormat = Exclude<DocumentFormat, 'google-doc'> | 'doc';
+
+export function agentDocumentFormat(
+  format: DocumentFormat,
+): AgentDocumentFormat {
+  return format === 'google-doc' ? 'doc' : format;
+}

package/src/index.ts

@@ -87,3 +87,18 @@ export type {
   SiteConfiguration,
   SyncConfigurationDefaults,
 } from './site-configuration.js';
+export {
+  agentDocumentFormat,
+  DOCUMENT_FORMAT_BADGES,
+  DOCUMENT_FORMAT_NOUNS,
+  DOCUMENT_FORMATS,
+  DOCUMENT_SOURCE_TYPES,
+  documentFormatOf,
+  documentSourceType,
+  isDocumentSourceType,
+} from './document-format.js';
+export type {
+  AgentDocumentFormat,
+  DocumentFormat,
+  DocumentSourceType,
+} from './document-format.js';

package/src/site-configuration.ts

@@ -27,8 +27,17 @@ export interface BrandConfiguration {
   readonly siteTitle: string;
   /** One sentence, used as the site-wide meta description. */
   readonly siteDescription: string;
-  /** Site-root-relative path of the favicon served from `public/`. */
+  /**
+   * Site-root-relative path of the favicon served from `public/`, which is
+   * also the mark in the header.
+   */
   readonly faviconPath: string;
+  /**
+   * The same mark drawn for a dark ground, when the light one would not show
+   * on it: the header shows it under the dark theme, and a browser whose
+   * interface is dark shows it in the tab.
+   */
+  readonly faviconDarkPath?: string;
 }
 
 export interface HomeConfiguration {
@@ -737,8 +746,16 @@ export function parseSiteConfiguration(input: unknown): SiteConfiguration {
   if (!faviconPath.startsWith('/')) {
     fail('brand.faviconPath', 'must be a site-root-relative path');
   }
+  const faviconDarkPath =
+    brandSource.faviconDarkPath === undefined
+      ? undefined
+      : text(brandSource, 'faviconDarkPath', 'brand.faviconDarkPath');
+  if (faviconDarkPath !== undefined && !faviconDarkPath.startsWith('/')) {
+    fail('brand.faviconDarkPath', 'must be a site-root-relative path');
+  }
   const brand: BrandConfiguration = {
     faviconPath,
+    ...(faviconDarkPath === undefined ? {} : { faviconDarkPath }),
     name: text(brandSource, 'name', 'brand.name'),
     siteDescription: text(
       brandSource,