@bendyline/squisq 1.2.2 → 1.4.0

package/src/markdown/types.ts

@@ -453,6 +453,22 @@ export interface MarkdownInlineMath extends MarkdownNodeBase {
   value: string;
 }
 
+/**
+ * Inline FontAwesome icon. Authored as `{[name]}` (bare) or
+ * `{[fa-<family>:name]}` (qualified) in markdown source. The parser
+ * resolves the token against the FA Free catalog and emits this node;
+ * unknown / ambiguous tokens stay as literal text.
+ */
+export interface MarkdownInlineIcon extends MarkdownNodeBase {
+  type: 'inlineIcon';
+  /** Token exactly as authored — e.g. `github` or `fa-solid:user`. */
+  token: string;
+  /** Resolved icon family. */
+  family: 'brands' | 'solid' | 'regular';
+  /** Resolved icon name (without the `fa-` prefix). */
+  name: string;
+}
+
 /**
  * A footnote reference [^id]. GFM extension.
  */
@@ -507,6 +523,25 @@ export interface MarkdownTextDirective extends MarkdownNodeBase {
   children: MarkdownInlineNode[];
 }
 
+/**
+ * An @-mention of a named entity such as a user or agent.
+ *
+ * Wire format: `@[Display Name](scheme:id)` — a regular Markdown link
+ * preceded by `@`, with a namespaced URL scheme that identifies what
+ * kind of entity is being mentioned. Parsers that don't know about
+ * mentions still render it as a link with text "Display Name" pointing
+ * at "scheme:id" — graceful fallback.
+ */
+export interface MarkdownMention extends MarkdownNodeBase {
+  type: 'mention';
+  /** Namespace for the mentioned entity (e.g. `"user"`). */
+  targetKind: string;
+  /** Stable identifier within the namespace. */
+  targetId: string;
+  /** Text shown to the reader. */
+  displayName: string;
+}
+
 // ============================================
 // Union Types
 // ============================================
@@ -543,7 +578,9 @@ export type MarkdownInlineNode =
   | MarkdownFootnoteReference
   | MarkdownLinkReference
   | MarkdownImageReference
-  | MarkdownTextDirective;
+  | MarkdownTextDirective
+  | MarkdownMention
+  | MarkdownInlineIcon;
 
 /**
  * Any node in the markdown tree. Includes structural nodes (listItem,

package/src/markdown/utils.ts

@@ -157,6 +157,109 @@ export function parseFrontmatter(yaml: string): Record<string, unknown> | null {
   return Object.keys(result).length > 0 ? result : null;
 }
 
+const FRONTMATTER_BLOCK_RE = /^---\r?\n([\s\S]*?)\r?\n---(\r?\n)?/;
+
+/** Quote a frontmatter scalar so it round-trips cleanly through `parseFrontmatter`. */
+function formatFrontmatterValue(value: string | number | boolean): string {
+  if (typeof value === 'boolean' || typeof value === 'number') return String(value);
+  // Quote when needed: leading/trailing whitespace, leading punctuation that
+  // could trigger YAML modes, or values that look like reserved literals.
+  const needsQuote =
+    /^\s|\s$/.test(value) ||
+    /^[!&*?|>%@`]/.test(value) ||
+    /[:#]/.test(value) ||
+    value === '' ||
+    value === 'true' ||
+    value === 'false' ||
+    /^-?\d+(\.\d+)?$/.test(value);
+  if (!needsQuote) return value;
+  // Prefer double quotes; escape any embedded double-quote / backslash.
+  const escaped = value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+  return `"${escaped}"`;
+}
+
+/**
+ * Update a markdown source string's YAML frontmatter block, applying the
+ * given key/value updates. A `null` or `undefined` value removes the key.
+ * If no frontmatter block exists and any non-null update is supplied, a
+ * new block is prepended; if every update is a removal and no block
+ * exists, the source is returned unchanged.
+ *
+ * Existing key order is preserved; new keys are appended in the order
+ * they appear in `updates`. The simple parser used here handles plain
+ * `key: value` pairs only — comments, multi-line scalars, and nested
+ * structures are left untouched (we only rewrite lines whose key matches
+ * one in `updates`).
+ *
+ * @param source - The markdown source string.
+ * @param updates - Map of key → new value (or null/undefined to remove).
+ * @returns The updated markdown source string.
+ */
+export function setFrontmatterValues(
+  source: string,
+  updates: Record<string, string | number | boolean | null | undefined>,
+): string {
+  const updateKeys = Object.keys(updates);
+  if (updateKeys.length === 0) return source;
+
+  const match = source.match(FRONTMATTER_BLOCK_RE);
+  const handled = new Set<string>();
+
+  // Existing frontmatter block — rewrite line-by-line, preserving order.
+  if (match) {
+    const inner = match[1];
+    const lines = inner.split(/\r?\n/);
+    const newLines: string[] = [];
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('#')) {
+        newLines.push(line);
+        continue;
+      }
+      const colonIdx = trimmed.indexOf(':');
+      if (colonIdx < 1) {
+        newLines.push(line);
+        continue;
+      }
+      const key = trimmed.slice(0, colonIdx).trim();
+      if (!Object.prototype.hasOwnProperty.call(updates, key)) {
+        newLines.push(line);
+        continue;
+      }
+      handled.add(key);
+      const next = updates[key];
+      if (next === null || next === undefined) continue; // remove
+      newLines.push(`${key}: ${formatFrontmatterValue(next)}`);
+    }
+
+    // Append any keys that weren't already present.
+    for (const key of updateKeys) {
+      if (handled.has(key)) continue;
+      const next = updates[key];
+      if (next === null || next === undefined) continue;
+      newLines.push(`${key}: ${formatFrontmatterValue(next)}`);
+    }
+
+    // If every line got removed, drop the block entirely.
+    const nonEmpty = newLines.filter((l) => l.trim().length > 0);
+    const rest = source.slice(match[0].length);
+    if (nonEmpty.length === 0) return rest;
+    return `---\n${newLines.join('\n')}\n---\n${rest}`;
+  }
+
+  // No existing block — only create one if there's at least one non-null
+  // value to write.
+  const fresh: string[] = [];
+  for (const key of updateKeys) {
+    const next = updates[key];
+    if (next === null || next === undefined) continue;
+    fresh.push(`${key}: ${formatFrontmatterValue(next)}`);
+  }
+  if (fresh.length === 0) return source;
+  return `---\n${fresh.join('\n')}\n---\n${source}`;
+}
+
 /**
  * Create a minimal MarkdownDocument from a list of block nodes.
  * Convenience function for programmatic document construction.
@@ -167,3 +270,59 @@ export function createDocument(...children: MarkdownDocument['children']): Markd
     children,
   };
 }
+
+/**
+ * Infer a human-readable title for a markdown document.
+ *
+ * Resolution order:
+ *   1. `title:` value in YAML frontmatter (when present and non-empty)
+ *   2. Text of the first heading found, walking top-level depth (H1, then
+ *      H2, etc.) — the shallowest heading wins regardless of source order
+ *
+ * Returns `undefined` when no usable title is found.
+ */
+export function inferDocumentTitle(doc: MarkdownDocument): string | undefined {
+  const fmTitle = doc.frontmatter?.title;
+  if (typeof fmTitle === 'string') {
+    const trimmed = fmTitle.trim();
+    if (trimmed) return trimmed;
+  }
+
+  let best: { depth: number; text: string } | null = null;
+  for (const node of doc.children) {
+    if (node.type !== 'heading') continue;
+    const text = extractPlainText(node).trim();
+    if (!text) continue;
+    if (best === null || node.depth < best.depth) {
+      best = { depth: node.depth, text };
+      if (best.depth === 1) break;
+    }
+  }
+
+  return best?.text;
+}
+
+/**
+ * Read a theme id from a markdown document's frontmatter.
+ *
+ * Checks the editor's canonical `squisq-theme` key first, then the
+ * shorter legacy aliases (`themeId`, `theme`). Returns `undefined`
+ * when none of them carry a non-empty string. Centralizing the lookup
+ * keeps the export pipelines (DOCX, PPTX, HTML, plain-HTML bundle) in
+ * sync with whatever the editor writes — adding a new frontmatter
+ * spelling later is a one-file change.
+ */
+export function readFrontmatterThemeId(
+  frontmatter: Record<string, unknown> | undefined,
+): string | undefined {
+  if (!frontmatter) return undefined;
+  const keys = ['squisq-theme', 'themeId', 'theme'] as const;
+  for (const key of keys) {
+    const raw = frontmatter[key];
+    if (typeof raw === 'string') {
+      const trimmed = raw.trim();
+      if (trimmed) return trimmed;
+    }
+  }
+  return undefined;
+}

package/src/recommend/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Template recommendations for the editor's block template picker.
+ *
+ * @example
+ * ```ts
+ * import { parseMarkdown } from '@bendyline/squisq/markdown';
+ * import { profileBlockContents, recommendTemplatesForBlock } from '@bendyline/squisq/recommend';
+ *
+ * const doc = parseMarkdown(blockBodySource);
+ * const profile = profileBlockContents(doc.children);
+ * const { recommended, rest } = recommendTemplatesForBlock(profile, ALL_TEMPLATE_NAMES);
+ * ```
+ */
+
+export type { BlockContentProfile, RecommendationResult } from './templates.js';
+export { profileBlockContents, recommendTemplatesForBlock } from './templates.js';

package/src/recommend/templates.ts

@@ -0,0 +1,273 @@
+/**
+ * Block template recommendations.
+ *
+ * Given a slice of markdown block nodes (the body underneath a heading),
+ * profile the content for image / video / quote / list / table / date /
+ * stat signals, then map that profile to the set of templates that make
+ * sense for the block. Used by the editor's template picker to surface a
+ * "Recommended for this block" section above the full template list.
+ */
+
+import { extractPlainText, findNodesByType, walkMarkdownTree } from '../markdown/utils.js';
+import type {
+  HtmlElement,
+  HtmlNode,
+  MarkdownBlockNode,
+  MarkdownHtmlBlock,
+  MarkdownNode,
+} from '../markdown/types.js';
+
+export interface BlockContentProfile {
+  hasImage: boolean;
+  imageCount: number;
+  hasVideo: boolean;
+  hasBlockquote: boolean;
+  hasList: boolean;
+  hasTable: boolean;
+  hasDate: boolean;
+  hasNumberHighlight: boolean;
+  wordCount: number;
+}
+
+export interface RecommendationResult {
+  recommended: string[];
+  rest: string[];
+}
+
+const EMPTY_PROFILE: BlockContentProfile = Object.freeze({
+  hasImage: false,
+  imageCount: 0,
+  hasVideo: false,
+  hasBlockquote: false,
+  hasList: false,
+  hasTable: false,
+  hasDate: false,
+  hasNumberHighlight: false,
+  wordCount: 0,
+});
+
+const DATE_PATTERNS: RegExp[] = [
+  /\b(January|February|March|April|May|June|July|August|September|October|November|December)\s+(\d{1,2},?\s+)?\d{4}\b/i,
+  /\b\d{1,2}\s+(January|February|March|April|May|June|July|August|September|October|November|December)\s+\d{4}\b/i,
+  /\b(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Sept|Oct|Nov|Dec)\.?\s+\d{1,2},?\s+\d{4}\b/i,
+  /\b\d{4}-\d{2}-\d{2}\b/,
+  /\b\d{1,2}\/\d{1,2}\/\d{2,4}\b/,
+  /\bQ[1-4]\s+\d{4}\b/,
+  /\b\d{4}s\b/,
+  /\b\d{1,2}(st|nd|rd|th)\s+century\b/i,
+];
+
+/**
+ * Matches a "highlight number" — a prominent figure suitable for a Stat
+ * Highlight block. Qualifies on any of:
+ *   - currency prefix:   `$2.3M`, `€500`, `¥1,234`
+ *   - unit suffix:       `50%`, `100 years`, `5×`, `2.3M`
+ *   - standalone large:  `1,234`, `5000`, `12,345`
+ * Plain small numbers (`42`) intentionally don't qualify.
+ */
+const NUMBER_HIGHLIGHT_RE =
+  /(?:[$€£¥]\s?\d+(?:[.,]\d+)*(?:\s?(?:[MBK]|million|billion|thousand))?|\d+(?:[.,]\d+)*\s?(?:%|‰|x|×|[MBK]|million|billion|thousand|percent|years?|days?|hours?)|\d{3,}(?:[.,]\d+)*)/i;
+
+const VIDEO_HOST_RE = /(youtube\.com|youtu\.be|vimeo\.com|wistia\.|loom\.com)/i;
+
+function htmlElementsByTag(root: MarkdownNode, tagNames: Set<string>): HtmlElement[] {
+  const blocks = findNodesByType<MarkdownHtmlBlock>(root, 'htmlBlock');
+  // Inline HTML (htmlInline) also carries htmlChildren; include both.
+  const inline = findNodesByType<MarkdownNode>(root, 'htmlInline') as Array<
+    MarkdownNode & { htmlChildren?: HtmlNode[] }
+  >;
+  const out: HtmlElement[] = [];
+  const visit = (n: HtmlNode): void => {
+    if (n.type === 'htmlElement') {
+      if (tagNames.has(n.tagName.toLowerCase())) out.push(n);
+      for (const c of n.children) visit(c);
+    }
+  };
+  for (const b of blocks) for (const c of b.htmlChildren) visit(c);
+  for (const i of inline) {
+    if (Array.isArray(i.htmlChildren)) for (const c of i.htmlChildren) visit(c);
+  }
+  return out;
+}
+
+/**
+ * Walk a slice of block nodes and summarize what kinds of content it
+ * contains. Cheap to run — no markdown parsing, just AST traversal.
+ */
+export function profileBlockContents(nodes: MarkdownBlockNode[]): BlockContentProfile {
+  if (!nodes || nodes.length === 0) return { ...EMPTY_PROFILE };
+
+  let imageCount = 0;
+  let hasBlockquote = false;
+  let hasList = false;
+  let hasTable = false;
+
+  const plainParts: string[] = [];
+
+  for (const node of nodes) {
+    imageCount += findNodesByType(node, 'image').length;
+    imageCount += findNodesByType(node, 'imageReference').length;
+    if (findNodesByType(node, 'blockquote').length > 0) hasBlockquote = true;
+    if (findNodesByType(node, 'list').length > 0) hasList = true;
+    if (findNodesByType(node, 'table').length > 0) hasTable = true;
+    plainParts.push(extractPlainText(node));
+  }
+
+  // HTML embeds: <img>, <video>, <iframe src=…video host>
+  const root: MarkdownNode = { type: 'document', children: nodes };
+  const imgTags = htmlElementsByTag(root, new Set(['img']));
+  imageCount += imgTags.length;
+
+  const videoTags = htmlElementsByTag(root, new Set(['video', 'iframe', 'source']));
+  let hasVideo = false;
+  for (const el of videoTags) {
+    if (el.tagName.toLowerCase() === 'video') {
+      hasVideo = true;
+      break;
+    }
+    const src = el.attributes.src || el.attributes.href || '';
+    if (VIDEO_HOST_RE.test(src)) {
+      hasVideo = true;
+      break;
+    }
+  }
+
+  // Link-only video embeds (markdown link to a known video host).
+  if (!hasVideo) {
+    const links = findNodesByType<MarkdownNode & { url?: string }>(root, 'link');
+    for (const link of links) {
+      if (link.url && VIDEO_HOST_RE.test(link.url)) {
+        hasVideo = true;
+        break;
+      }
+    }
+  }
+
+  const plainText = plainParts.join(' ').trim();
+  const wordCount = plainText ? plainText.split(/\s+/).length : 0;
+
+  let hasDate = false;
+  for (const re of DATE_PATTERNS) {
+    if (re.test(plainText)) {
+      hasDate = true;
+      break;
+    }
+  }
+
+  // Number highlight: a paragraph that's mostly a single prominent figure.
+  let hasNumberHighlight = false;
+  walkMarkdownTree(root, (n) => {
+    if (hasNumberHighlight) return true;
+    if (n.type !== 'paragraph') return;
+    const text = extractPlainText(n).trim();
+    if (!text) return true;
+    const m = text.match(NUMBER_HIGHLIGHT_RE);
+    if (!m) return true;
+    // Paragraph qualifies when its word count is small AND a prominent
+    // number occupies a meaningful chunk of it. Keeps "the company grew
+    // 50% last year" from triggering, but accepts "$2.3M raised".
+    const words = text.split(/\s+/).length;
+    if (words <= 8) hasNumberHighlight = true;
+    return true;
+  });
+
+  return {
+    hasImage: imageCount > 0,
+    imageCount,
+    hasVideo,
+    hasBlockquote,
+    hasList,
+    hasTable,
+    hasDate,
+    hasNumberHighlight,
+    wordCount,
+  };
+}
+
+// ── Recommendation rules ───────────────────────────────────────────
+
+const UNIVERSAL_DEFAULTS = ['title', 'sectionHeader', 'factCard', 'twoColumn'];
+
+/**
+ * Given a content profile, return the canonical template-name list that
+ * should appear in the "Recommended" bucket. Caller is responsible for
+ * preserving deduplication / ordering when intersecting with the full
+ * template list (see {@link recommendTemplatesForBlock}).
+ */
+function recommendedNamesForProfile(profile: BlockContentProfile): string[] {
+  const names = new Set<string>();
+  let anyContentSignal = false;
+
+  if (profile.hasImage) {
+    anyContentSignal = true;
+    names.add('imageWithCaption');
+    names.add('leftFeature');
+    names.add('rightFeature');
+    if (profile.imageCount >= 2) names.add('photoGrid');
+  }
+
+  if (profile.hasVideo) {
+    anyContentSignal = true;
+    names.add('videoWithCaption');
+    if (profile.hasBlockquote) names.add('videoPullQuote');
+  }
+
+  if (profile.hasBlockquote) {
+    anyContentSignal = true;
+    names.add('quote');
+    names.add('pullQuote');
+    names.add('fullBleedQuote');
+  }
+
+  if (profile.hasList) {
+    anyContentSignal = true;
+    names.add('list');
+  }
+
+  if (profile.hasTable) {
+    anyContentSignal = true;
+    names.add('dataTable');
+    names.add('comparisonBar');
+  }
+
+  if (profile.hasDate) {
+    anyContentSignal = true;
+    names.add('dateEvent');
+  }
+
+  if (profile.hasNumberHighlight) {
+    anyContentSignal = true;
+    names.add('statHighlight');
+  }
+
+  if (anyContentSignal) {
+    // Universal pair only — keep recommended focused.
+    names.add('title');
+    names.add('sectionHeader');
+  } else {
+    for (const n of UNIVERSAL_DEFAULTS) names.add(n);
+  }
+
+  return Array.from(names);
+}
+
+/**
+ * Split a flat list of template names into a "Recommended" bucket
+ * (matches the active block's content profile) and a "rest" bucket
+ * (everything else). Both buckets preserve the input ordering of
+ * `allNames`, so the visual layout stays predictable as templates are
+ * added.
+ */
+export function recommendTemplatesForBlock(
+  profile: BlockContentProfile,
+  allNames: readonly string[],
+): RecommendationResult {
+  const desired = new Set(recommendedNamesForProfile(profile));
+  const recommended: string[] = [];
+  const rest: string[] = [];
+  for (const name of allNames) {
+    if (desired.has(name)) recommended.push(name);
+    else rest.push(name);
+  }
+  return { recommended, rest };
+}

package/src/schemas/BlockTemplates.ts

@@ -3,17 +3,17 @@
  *
  * Defines a template system for AI-generated doc blocks. Instead of
  * specifying low-level layers, positions, and animations, AI can use
- * high-level templates like "titleBlock" or "statHighlight" with simple
+ * high-level templates like "title" or "statHighlight" with simple
  * content parameters.
  *
  * Templates are expanded into full Block structures at render time,
  * ensuring consistent styling and reducing AI generation errors.
  *
  * Template Types:
- * - titleBlock: Doc intro with title + subtitle
+ * - title: Doc intro with title + subtitle
  * - sectionHeader: Colored section divider
  * - statHighlight: Big number/stat with description
- * - quoteBlock: Large centered quote
+ * - quote: Large centered quote
  * - factCard: Key fact with explanation
  * - twoColumn: Side-by-side comparison
  * - dateEvent: Timeline-style date + description
@@ -116,7 +116,7 @@ interface BaseTemplateBlock {
  * Title block - doc intro with large title and subtitle.
  */
 export interface TitleBlockInput extends BaseTemplateBlock {
-  template: 'titleBlock';
+  template: 'title';
   /** Main title text */
   title: string;
   /** Subtitle or tagline (supports \n for line breaks) */
@@ -164,7 +164,7 @@ export interface StatHighlightInput extends BaseTemplateBlock {
  * Quote block - large centered quote text.
  */
 export interface QuoteBlockInput extends BaseTemplateBlock {
-  template: 'quoteBlock';
+  template: 'quote';
   /** The quote text (supports \n for line breaks) */
   quote: string;
   /** Attribution (author, source) */
@@ -252,6 +252,47 @@ export interface ImageWithCaptionInput extends BaseTemplateBlock {
   imageLicense?: string;
 }
 
+/**
+ * Shared fields for left/right feature blocks. A "feature" pairs an
+ * image on one side of the block with a title and body paragraph on
+ * the other — a common editorial layout for product highlights,
+ * profile callouts, or section intros.
+ */
+interface FeatureInputBase extends BaseTemplateBlock {
+  /** Path to the feature image. */
+  imageSrc: string;
+  /** Alt text for accessibility. */
+  imageAlt?: string;
+  /**
+   * Explicit display width of the image, in pixels (typically pulled
+   * from a `<img width>` attribute when the WYSIWYG editor resized it).
+   * When set, the renderer treats the image as a sized asset and
+   * centers it inside its half with padding instead of stretching it
+   * to fill the cell.
+   */
+  imageWidth?: number;
+  /** Explicit display height of the image, in pixels. */
+  imageHeight?: number;
+  /** Heading / title text shown next to the image. */
+  title?: string;
+  /** Body text shown below the title. */
+  body?: string;
+}
+
+/**
+ * Left feature — image on the left, title + body stacked on the right.
+ */
+export interface LeftFeatureInput extends FeatureInputBase {
+  template: 'leftFeature';
+}
+
+/**
+ * Right feature — image on the right, title + body stacked on the left.
+ */
+export interface RightFeatureInput extends FeatureInputBase {
+  template: 'rightFeature';
+}
+
 /**
  * Map block - geographic map showing article location.
  *
@@ -260,7 +301,7 @@ export interface ImageWithCaptionInput extends BaseTemplateBlock {
  * See docs/MAP_TILES.md for available tile styles and attribution.
  */
 export interface MapBlockInput extends BaseTemplateBlock {
-  template: 'mapBlock';
+  template: 'map';
   /** Map center coordinates */
   center: {
     lat: number;
@@ -299,7 +340,7 @@ export interface FullBleedQuoteInput extends BaseTemplateBlock {
  * Good for enumerations like "things to see" or "key features".
  */
 export interface ListBlockInput extends BaseTemplateBlock {
-  template: 'listBlock';
+  template: 'list';
   /** List items (3-5 recommended) */
   items: string[];
   /** Optional header above the list */
@@ -459,6 +500,8 @@ export type TemplateBlock =
   | TwoColumnInput
   | DateEventInput
   | ImageWithCaptionInput
+  | LeftFeatureInput
+  | RightFeatureInput
   | MapBlockInput
   | FullBleedQuoteInput
   | ListBlockInput