@rathnasgala2/template 3.0.0 → 3.1.0

package/src/core/internal/interactions.js

@@ -0,0 +1,349 @@
+/**
+ * Reader interactions, render side: validation of `build-input.modules.interactions`,
+ * the server-rendered `<section class="g-interactions">` page contract the
+ * browser script (`src/modules/interactions/browser/gala-interactions.js`)
+ * enhances, and the script asset itself. The template renders markup only;
+ * every request, token and comment lives in the browser script and the API.
+ */
+
+import { readFile } from 'node:fs/promises';
+
+import { RenderPolicyViolationError } from '../errors.js';
+import { escapeHtml } from './skeleton.js';
+import { icon } from './icons.js';
+
+/** @type {string} the emitted script's output-relative path */
+export const INTERACTIONS_SCRIPT_PATH = 'assets/gala-interactions-v1.js';
+
+/** @type {string} */
+export const INTERACTIONS_SCRIPT_MEDIA_TYPE =
+  'application/javascript; charset=utf-8';
+
+const INTERACTIONS_SCRIPT_SOURCE_URL = new URL(
+  '../../modules/interactions/browser/gala-interactions.js',
+  import.meta.url,
+);
+
+/** @type {string} */
+const CONFIG_SCHEMA_ID = 'urn:gala:schema:interactions-config:2.0.0';
+
+/** The approved reaction emoji (design section 3). */
+export const APPROVED_REACTION_EMOJI = Object.freeze([
+  '\u{1F44D}',
+  '❤️',
+  '\u{1F4A1}',
+  '\u{1F389}',
+  '\u{1F602}',
+  '\u{1F92F}',
+  '\u{1F64F}',
+  '\u{1F525}',
+  '\u{1F44F}',
+  '\u{1F62E}',
+  '\u{1F622}',
+  '\u{1F914}',
+  '✨',
+  '\u{1F680}',
+  '\u{1F4AF}',
+  '\u{1F440}',
+]);
+
+/**
+ * @param {unknown} value any value
+ * @returns {value is Record<string, unknown>} whether it is a plain object
+ */
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Throw unless `value` is an object with exactly the `allowed` keys (all
+ * required).
+ *
+ * @param {unknown} value candidate
+ * @param {readonly string[]} keys the exact key set
+ * @param {string} where location for the message
+ * @returns {Record<string, unknown>} the object
+ */
+function exactObject(value, keys, where) {
+  if (!isRecord(value)) {
+    throw new RenderPolicyViolationError(`${where} must be an object`);
+  }
+  for (const key of Object.keys(value)) {
+    if (!keys.includes(key)) {
+      throw new RenderPolicyViolationError(`${where}.${key} is not allowed`);
+    }
+  }
+  for (const key of keys) {
+    if (!(key in value)) {
+      throw new RenderPolicyViolationError(`${where}.${key} is required`);
+    }
+  }
+  return value;
+}
+
+/**
+ * @param {unknown} value candidate
+ * @param {string} where location for the message
+ * @returns {boolean} the boolean
+ */
+function boolean(value, where) {
+  if (typeof value !== 'boolean') {
+    throw new RenderPolicyViolationError(`${where} must be a boolean`);
+  }
+  return value;
+}
+
+/**
+ * An `https` origin, or an `http` origin on localhost / 127.0.0.1 (the local
+ * stack), with no path, query or fragment.
+ *
+ * @param {unknown} value candidate
+ * @param {string} where location for the message
+ * @returns {string} the origin
+ */
+function origin(value, where) {
+  let parsed;
+  try {
+    parsed = new URL(String(value));
+  } catch {
+    throw new RenderPolicyViolationError(`${where} must be an origin URL`);
+  }
+  const local =
+    parsed.protocol === 'http:' &&
+    (parsed.hostname === 'localhost' || parsed.hostname === '127.0.0.1');
+  if (
+    typeof value !== 'string' ||
+    parsed.origin !== value ||
+    (parsed.protocol !== 'https:' && !local)
+  ) {
+    throw new RenderPolicyViolationError(
+      `${where} must be an https origin (or an http localhost origin) with no path`,
+    );
+  }
+  return value;
+}
+
+/**
+ * Validate `build-input.modules.interactions` (design sections 3 and 4).
+ * `placements` stays empty and no other module is admitted; both are checked
+ * by the caller.
+ *
+ * @param {unknown} candidate the module selection value
+ * @returns {import('../../../types/index.d.ts').InteractionsModule} the
+ *   validated, frozen-shape module
+ */
+export function validateInteractionsModule(candidate) {
+  const where = 'build-input.modules.interactions';
+  const module = exactObject(
+    candidate,
+    ['config', 'apiOrigin', 'appOrigin'],
+    where,
+  );
+  const apiOrigin = origin(module.apiOrigin, `${where}.apiOrigin`);
+  const appOrigin = origin(module.appOrigin, `${where}.appOrigin`);
+  const config = exactObject(
+    module.config,
+    ['schemaId', 'schemaVersion', 'reactions', 'comments', 'publicCounts'],
+    `${where}.config`,
+  );
+  if (
+    config.schemaId !== CONFIG_SCHEMA_ID ||
+    config.schemaVersion !== '2.0.0'
+  ) {
+    throw new RenderPolicyViolationError(
+      `${where}.config.schemaId must be ${CONFIG_SCHEMA_ID} with schemaVersion 2.0.0`,
+    );
+  }
+  const reactions = exactObject(
+    config.reactions,
+    ['enabled', 'definitions'],
+    `${where}.config.reactions`,
+  );
+  boolean(reactions.enabled, `${where}.config.reactions.enabled`);
+  const definitions = reactions.definitions;
+  if (!Array.isArray(definitions) || definitions.length > 16) {
+    throw new RenderPolicyViolationError(
+      `${where}.config.reactions.definitions must be an array of at most 16`,
+    );
+  }
+  const keys = new Set();
+  const orders = new Set();
+  definitions.forEach((definition, index) => {
+    const at = `${where}.config.reactions.definitions[${index}]`;
+    const item = exactObject(
+      definition,
+      ['key', 'label', 'visual', 'order', 'enabled'],
+      at,
+    );
+    if (
+      typeof item.key !== 'string' ||
+      !/^[a-z][a-z0-9-]{1,31}$/.test(item.key) ||
+      item.key === 'like'
+    ) {
+      throw new RenderPolicyViolationError(
+        `${at}.key must match ^[a-z][a-z0-9-]{1,31}$ and must not be "like"`,
+      );
+    }
+    if (keys.has(item.key)) {
+      throw new RenderPolicyViolationError(`${at}.key is duplicated`);
+    }
+    keys.add(item.key);
+    if (
+      typeof item.label !== 'string' ||
+      [...item.label].length < 1 ||
+      [...item.label].length > 32
+    ) {
+      throw new RenderPolicyViolationError(
+        `${at}.label must be 1 to 32 characters`,
+      );
+    }
+    const visual = exactObject(item.visual, ['kind', 'token'], `${at}.visual`);
+    if (
+      visual.kind !== 'emoji' ||
+      !APPROVED_REACTION_EMOJI.includes(/** @type {string} */ (visual.token))
+    ) {
+      throw new RenderPolicyViolationError(
+        `${at}.visual must be an emoji from the approved list`,
+      );
+    }
+    if (
+      !Number.isInteger(item.order) ||
+      /** @type {number} */ (item.order) < 1 ||
+      /** @type {number} */ (item.order) > 16
+    ) {
+      throw new RenderPolicyViolationError(
+        `${at}.order must be an integer from 1 to 16`,
+      );
+    }
+    if (orders.has(item.order)) {
+      throw new RenderPolicyViolationError(`${at}.order is duplicated`);
+    }
+    orders.add(item.order);
+    boolean(item.enabled, `${at}.enabled`);
+  });
+  const comments = exactObject(
+    config.comments,
+    ['enabled', 'allowReplies', 'maxDepth'],
+    `${where}.config.comments`,
+  );
+  boolean(comments.enabled, `${where}.config.comments.enabled`);
+  boolean(comments.allowReplies, `${where}.config.comments.allowReplies`);
+  if (
+    !Number.isInteger(comments.maxDepth) ||
+    /** @type {number} */ (comments.maxDepth) < 1 ||
+    /** @type {number} */ (comments.maxDepth) > 4
+  ) {
+    throw new RenderPolicyViolationError(
+      `${where}.config.comments.maxDepth must be an integer from 1 to 4`,
+    );
+  }
+  const counts = exactObject(
+    config.publicCounts,
+    ['reactions', 'comments'],
+    `${where}.config.publicCounts`,
+  );
+  boolean(counts.reactions, `${where}.config.publicCounts.reactions`);
+  boolean(counts.comments, `${where}.config.publicCounts.comments`);
+  return /** @type {import('../../../types/index.d.ts').InteractionsModule} */ (
+    /** @type {unknown} */ ({ config, apiOrigin, appOrigin })
+  );
+}
+
+/**
+ * Whether the module puts anything on article pages: it is present and at
+ * least one of reactions and comments is enabled.
+ *
+ * @param {import('../../../types/index.d.ts').InteractionsModule | undefined} module
+ *   the validated module, if any
+ * @returns {boolean} whether article routes are interaction-bearing
+ */
+export function interactionsActive(module) {
+  return (
+    module !== undefined &&
+    (module.config.reactions.enabled || module.config.comments.enabled)
+  );
+}
+
+/**
+ * Render the `<section class="g-interactions">` for one article.
+ *
+ * @param {object} input render input
+ * @param {import('../../../types/index.d.ts').InteractionsModule} input.module
+ *   the validated module
+ * @param {Readonly<Record<string, string | ((...args: string[]) => string)>>} input.messages
+ *   the chrome message catalog
+ * @param {string} input.publicationId the build input's publication id
+ * @param {string} input.contentId the article's front matter id
+ * @param {string} input.canonicalUrl the absolute canonical article URL
+ * @returns {string} the section markup (empty when nothing is enabled)
+ */
+export function renderInteractionsSection({
+  module,
+  messages,
+  publicationId,
+  contentId,
+  canonicalUrl,
+}) {
+  if (!interactionsActive(module)) return '';
+  const { config } = module;
+  const text = (/** @type {string} */ key) =>
+    escapeHtml(/** @type {string} */ (messages[key]));
+  const reactionButtons = config.reactions.enabled
+    ? `<button type="button" class="g-reaction" data-reaction-key="like" aria-pressed="false" disabled>` +
+      `<span class="g-reaction__icon" aria-hidden="true">${icon('heart')}</span>` +
+      `<span class="g-reaction__label">${text('likeLabel')}</span>` +
+      `<span class="g-reaction__count" data-gala-count></span></button>` +
+      [...config.reactions.definitions]
+        .filter((definition) => definition.enabled)
+        .sort((a, b) => a.order - b.order)
+        .map(
+          (definition) =>
+            `<button type="button" class="g-reaction" data-reaction-key="${escapeHtml(definition.key)}" aria-pressed="false" disabled>` +
+            `<span class="g-reaction__icon" aria-hidden="true">${escapeHtml(definition.visual.token)}</span>` +
+            `<span class="g-reaction__label">${escapeHtml(definition.label)}</span>` +
+            `<span class="g-reaction__count" data-gala-count></span></button>`,
+        )
+        .join('')
+    : '';
+  const reactions = config.reactions.enabled
+    ? `<div class="g-reactions" data-gala-reactions role="group" aria-label="${text('reactionsGroupLabel')}">${reactionButtons}</div>`
+    : '';
+  const comments = config.comments.enabled
+    ? `<div class="g-comments" data-gala-comments>` +
+      `<h3 class="g-comments__title">${text('commentsHeading')} <span class="g-comments__count" data-gala-comment-count></span></h3>` +
+      `<p class="g-interactions__notice" data-gala-static-notice>${text('interactionsNeedScriptNotice')}</p>` +
+      `<div class="g-composer-slot" data-gala-composer-slot></div>` +
+      `<ol class="g-comment-list" data-gala-comment-list></ol>` +
+      `<button type="button" class="g-comments__more" data-gala-more hidden>${text('showMoreCommentsLabel')}</button>` +
+      `</div>`
+    : '';
+  const flag = (/** @type {boolean} */ value) => (value ? 'true' : 'false');
+  const staticNoticeForReactionsOnly =
+    !config.comments.enabled && config.reactions.enabled
+      ? `<p class="g-interactions__notice" data-gala-static-notice>${text('interactionsNeedScriptNotice')}</p>`
+      : '';
+  return (
+    `<section class="g-interactions" id="comments" aria-labelledby="g-interactions-title" data-gala-interactions ` +
+    `data-api-origin="${escapeHtml(module.apiOrigin)}" data-app-origin="${escapeHtml(module.appOrigin)}" ` +
+    `data-publication-id="${escapeHtml(publicationId)}" data-content-id="${escapeHtml(contentId)}" ` +
+    `data-canonical-url="${escapeHtml(canonicalUrl)}" ` +
+    `data-reactions-enabled="${flag(config.reactions.enabled)}" data-comments-enabled="${flag(config.comments.enabled)}" ` +
+    `data-count-reactions="${flag(config.publicCounts.reactions)}" data-count-comments="${flag(config.publicCounts.comments)}" ` +
+    `data-allow-replies="${flag(config.comments.allowReplies)}" data-max-depth="${config.comments.maxDepth}">` +
+    `<h2 id="g-interactions-title" class="g-interactions__title">${text('interactionsHeading')}</h2>` +
+    reactions +
+    staticNoticeForReactionsOnly +
+    comments +
+    `<div class="g-interactions__status" role="status" aria-live="polite" data-gala-status></div>` +
+    `</section>`
+  );
+}
+
+/**
+ * Read the browser script's bytes from the template package.
+ *
+ * @returns {Promise<Buffer>} the script bytes
+ */
+export function loadInteractionsScript() {
+  return readFile(INTERACTIONS_SCRIPT_SOURCE_URL);
+}

package/src/core/internal/messages.js

@@ -95,6 +95,12 @@ const CATALOGS = Object.freeze({
     keepReadingHeading: 'Keep reading',
     /** @type {(tag: string) => string} */
     moreInTagLabel: (tag) => `More in ${tag}`,
+    interactionsHeading: 'Responses',
+    reactionsGroupLabel: 'Reactions',
+    likeLabel: 'Like',
+    commentsHeading: 'Conversation',
+    interactionsNeedScriptNotice: 'Reactions and comments need JavaScript.',
+    showMoreCommentsLabel: 'Show more comments',
     shareLabel: 'Share',
     copyLinkLabel: 'Copy link to this article',
     saveForLaterLabel: 'Save for later',

package/src/core/internal/page-kinds.js

@@ -70,6 +70,10 @@ import {
 import { truncateAtWord } from './seo.js';
 import { createStructuredData } from './structured-data.js';
 import { icon } from './icons.js';
+import {
+  interactionsActive,
+  renderInteractionsSection,
+} from './interactions.js';
 import { getMessages } from './messages.js';
 import { resolveTextDirection } from './text-direction.js';
 import { deriveAuthorSlugs, routeSegmentForLabel } from './route-labels.js';
@@ -176,6 +180,8 @@ function paginate(items, pageSize) {
  *   one place that can turn this into an absolute derivative URL, because
  *   only it has run the media pipeline and knows the derivative
  *   output path a given `sourceDigest` produced)
+ * @property {boolean} [interactionBearing] whether this page carries the
+ *   reader-interactions section (article pages when the module is on)
  * @property {string} [robotsContent] an optional
  *   `<meta name="robots">` content value (e.g. `'noindex, follow'` for
  *   `status: "unlisted"` content); omitted entirely for ordinarily indexable
@@ -352,11 +358,17 @@ export function homeDocumentTitle(name, tagline) {
  *   processed derivative renders as the placeholder/monogram fallback
  * @param {Readonly<Record<string, {width: number, height: number}>>} [options.mediaDimensions]
  *   the media pipeline's pixel dimensions per derivative path
+ * @param {import('../../../types/index.d.ts').InteractionsModule} [options.interactions]
+ *   the validated interactions module; when set, every article page carries
+ *   the interactions section and is interaction-bearing
  * @returns {GeneratedPage[]} every generated page, in a stable, deterministic
  *   order
  */
 export function buildGeneratedPages(validatedInput, options = {}) {
   const { publication, authors, content, basePath, baseUrl } = validatedInput;
+  const interactionsModule = interactionsActive(options.interactions)
+    ? options.interactions
+    : undefined;
   const publicBasePath = derivePublicBasePath(baseUrl, basePath);
   const messages = getMessages(publication.defaultLanguage);
   const authorsById = new Map(authors.map((author) => [author.id, author]));
@@ -611,7 +623,7 @@ export function buildGeneratedPages(validatedInput, options = {}) {
   });
 
   const newsletterHtml = renderNewsletterPanel({
-    newsletter: /** @type {{newsletter?: unknown}} */ (publication).newsletter,
+    newsletter: publication.newsletter,
     messages,
   });
 
@@ -788,6 +800,7 @@ export function buildGeneratedPages(validatedInput, options = {}) {
 
     let foot = '';
     let after = '';
+    let interactions = '';
     if (isArticle) {
       const authorCards = ui
         .recordAuthors(record)
@@ -835,7 +848,16 @@ export function buildGeneratedPages(validatedInput, options = {}) {
         newer || older
           ? `<nav class="g-pager" aria-label="${text('moreArticlesNavigationLabel')}">${newer ? pagerLink(newer, false) : ''}${older ? pagerLink(older, true) : ''}</nav>`
           : '';
-      foot = `<div class="g-wrap g-article-foot">${authorCards}${seriesBox}${pager}</div>`;
+      interactions = interactionsModule
+        ? renderInteractionsSection({
+            module: interactionsModule,
+            messages,
+            publicationId: publication.id,
+            contentId: frontmatter.id,
+            canonicalUrl: absolute(recordHref(record)),
+          })
+        : '';
+      foot = `<div class="g-wrap g-article-foot">${authorCards}${interactions}${seriesBox}${pager}</div>`;
       const related = selectRelatedArticles(record, publishedArticles);
       after =
         related.length > 0
@@ -904,6 +926,7 @@ export function buildGeneratedPages(validatedInput, options = {}) {
         : undefined,
       robotsContent:
         frontmatter.status === 'unlisted' ? 'noindex, follow' : undefined,
+      interactionBearing: Boolean(interactions),
       lastModified: contentLastModified(frontmatter),
       bodyHtml:
         `<article class="g-article">${isArticle ? '<div class="g-progress" aria-hidden="true"></div>' : ''}${head}${cover}` +

package/src/core/internal/render-policy-content.js

@@ -239,6 +239,14 @@ export const ADMITTED_LANGUAGE_CLASSES = Object.freeze(
   HIGHLIGHT_GRAMMARS.map((grammar) => `language-${grammar}`),
 );
 
+/**
+ * The production Galascribe API origin. The blog CSP always allows it in
+ * `connect-src` (reader interactions design D8), interactions on or off.
+ *
+ * @type {string}
+ */
+export const PRODUCTION_API_ORIGIN = 'https://api.galascribe.com';
+
 /**
  * The CSP specification explicitly ignores `frame-ancestors`
  * (and `report-uri`/`sandbox`, neither used here) when a policy is
@@ -262,16 +270,19 @@ export const CSP_HEADER_ONLY_DIRECTIVES = Object.freeze([
  * `<meta http-equiv="Content-Security-Policy">` tag: {@link CSP_HEADER_ONLY_DIRECTIVES}
  * is excluded. Directive order is byte-exact, minus
  * the excluded directive; every directive's value list is already sorted
- * bytewise and duplicate-free because this renderer materializes no module
- * package, configuration, output or runtime, so this string is
- * byte-identical on every route.
+ * bytewise and duplicate-free. `connect-src` always admits the production
+ * Galascribe API origin (reader interactions, whether or not the module is
+ * on), so this string is byte-identical on every route of every production
+ * build. Only the local stack's differing interactions `apiOrigin` is
+ * appended per build ({@link contentSecurityPolicyMeta}).
  *
  * @type {string}
  */
 export const CONTENT_SECURITY_POLICY_META_BASELINE =
   "default-src 'none'; base-uri 'none'; object-src 'none'; " +
   "form-action 'none'; script-src 'self'; " +
-  "style-src 'self'; img-src 'self'; font-src 'self'; connect-src 'self'; " +
+  "style-src 'self'; img-src 'self'; font-src 'self'; " +
+  `connect-src 'self' ${PRODUCTION_API_ORIGIN}; ` +
   "media-src 'self'; manifest-src 'self'; worker-src 'none'";
 
 /**
@@ -287,9 +298,33 @@ export const CONTENT_SECURITY_POLICY_META_BASELINE =
 export const CONTENT_SECURITY_POLICY_COMPLETE =
   "default-src 'none'; base-uri 'none'; object-src 'none'; " +
   "frame-ancestors 'none'; form-action 'none'; script-src 'self'; " +
-  "style-src 'self'; img-src 'self'; font-src 'self'; connect-src 'self'; " +
+  "style-src 'self'; img-src 'self'; font-src 'self'; " +
+  `connect-src 'self' ${PRODUCTION_API_ORIGIN}; ` +
   "media-src 'self'; manifest-src 'self'; worker-src 'none'";
 
+/**
+ * The meta-safe CSP for one build. Identical to
+ * {@link CONTENT_SECURITY_POLICY_META_BASELINE} unless the interactions
+ * module names a different API origin (local stack only), in which case that
+ * origin is added to `connect-src`, sorted bytewise with the other sources
+ * and de-duplicated.
+ *
+ * @param {string | undefined} [apiOrigin] the interactions module's
+ *   `apiOrigin`, when the module is on
+ * @returns {string} the CSP directive string for the `<meta>` tag
+ */
+export function contentSecurityPolicyMeta(apiOrigin) {
+  if (apiOrigin === undefined || apiOrigin === PRODUCTION_API_ORIGIN) {
+    return CONTENT_SECURITY_POLICY_META_BASELINE;
+  }
+  const sources = [...new Set(["'self'", PRODUCTION_API_ORIGIN, apiOrigin])];
+  sources.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  return CONTENT_SECURITY_POLICY_META_BASELINE.replace(
+    `connect-src 'self' ${PRODUCTION_API_ORIGIN};`,
+    `connect-src ${sources.join(' ')};`,
+  );
+}
+
 /**
  * Build the exact plain-object document `contracts/render-policy.jcs`
  * publishes: `name`, `version` byte-equal to the template lock's

package/src/core/internal/robots.js

@@ -3,10 +3,8 @@
  *
  * Every site allows all crawlers and names its sitemap by absolute URL. The
  * publication may additionally opt out of AI training and AI-assistant
- * crawlers through `publication.crawlers.ai` (`"allow"` | `"block"`, absent
- * means allow). The field is read defensively, exactly like
- * `publication.newsletter`: a build input that predates it, or carries any
- * other value, is treated as `"allow"`.
+ * crawlers through the validated `publication.crawlers.ai` (`"allow"` |
+ * `"block"`; absent means allow).
  *
  * Unlisted (`noindex`) pages are deliberately not disallowed here: a
  * crawler can only honour a `noindex` directive on a page it is allowed to
@@ -45,18 +43,12 @@ export const AI_CRAWLER_USER_AGENTS = Object.freeze([
 ]);
 
 /**
- * @param {unknown} publication `publication` (may predate `crawlers`)
+ * @param {{crawlers?: {ai: 'allow' | 'block'}}} publication the validated
+ *   `publication` (`crawlers` is optional; absent means allow)
  * @returns {'allow' | 'block'} the AI crawler policy
  */
 export function readAiCrawlerPolicy(publication) {
-  const crawlers = /** @type {{crawlers?: unknown} | undefined} */ (
-    publication && typeof publication === 'object' ? publication : undefined
-  )?.crawlers;
-  const ai =
-    crawlers && typeof crawlers === 'object'
-      ? /** @type {{ai?: unknown}} */ (crawlers).ai
-      : undefined;
-  return ai === 'block' ? 'block' : 'allow';
+  return publication.crawlers?.ai ?? 'allow';
 }
 
 /**