@bendyline/squisq 1.4.0 → 1.5.0

package/src/markdown/stringify.ts

@@ -16,6 +16,60 @@ import { toMdast } from './convert.js';
 // Cache the default processor (all extensions, default formatting) to avoid rebuilding on every call.
 let defaultProcessor: any;
 
+// ============================================
+// Annotation-span unescaping
+// ============================================
+
+// Quoted runs as they appear in remark-stringify output. Backslashes inside
+// the span are doubled by remark (a literal `\` before punctuation becomes
+// `\\`), so `\\.` covers both authored escapes and remark's own.
+const DQ_RUN = `"(?:[^"\\\\]|\\\\.)*"`;
+const SQ_RUN = `'(?:[^'\\\\]|\\\\.)*'`;
+
+/**
+ * A `{[…]}` template-annotation (or inline-icon) span as it appears in
+ * remark output: `{\[inner]}`, where `inner` may contain backslash escapes
+ * and quoted runs (which may themselves contain `]`).
+ */
+const ESCAPED_TEMPLATE_SPAN_RE = new RegExp(
+  `\\{\\\\\\[((?:${DQ_RUN}|${SQ_RUN}|\\\\.|[^\\]\\\\])+)\\]\\}`,
+  'g',
+);
+
+/** A heading line (annotations are only emitted trailing on headings). */
+const HEADING_LINE_RE = /^#{1,6} .*$/gm;
+
+/**
+ * The trailing Pandoc `{…}` span on a heading line, possibly followed by an
+ * already-unescaped `{[…]}` template span (canonical emit order).
+ */
+const TRAILING_ESCAPED_PANDOC_SPAN_RE = new RegExp(
+  `\\{(?!\\\\?\\[)((?:${DQ_RUN}|${SQ_RUN}|\\\\.|[^}\\\\])*)\\}(?=\\s*(?:\\{\\[.*)?$)`,
+);
+
+/**
+ * Backslash+punctuation pairs that are safe to unescape inside an
+ * annotation span: the bare character re-parses as literal text in
+ * trailing-heading position, so removing the backslash is purely
+ * cosmetic and round-trips.
+ *
+ * Deliberately EXCLUDED (left escaped in the emitted markdown): emphasis
+ * and other inline-construct openers (`*`, `_`, `` ` ``, `~`, `<`, `>`,
+ * `&`, `!`, `|`, `^`). Unescaping those could make remark-parse split the
+ * heading's text run into inline nodes on reparse, which would hide the
+ * annotation from the extractor. remark-parse resolves the surviving
+ * `\X` escapes back to bare characters, so values still round-trip —
+ * the escapes are a cosmetic cost only.
+ *
+ * Pairs are consumed left to right, so an authored `\"` that remark
+ * doubled to `\\"` correctly comes back as `\"`.
+ */
+const UNESCAPE_PUNCT_RE = /\\([\\[\]:#.,+=/?;@%$(){}'"-])/g;
+
+function unescapeMarkdownPunct(text: string): string {
+  return text.replace(UNESCAPE_PUNCT_RE, '$1');
+}
+
 /**
  * Serialize a MarkdownDocument back to a markdown string.
  *
@@ -106,9 +160,36 @@ export function stringifyMarkdown(doc: MarkdownDocument, options?: StringifyOpti
   // Stringify mdast → markdown string
   const result = processor.stringify(mdastTree) as string;
 
-  // remark-stringify escapes `[` in text nodes (to prevent link syntax),
-  // which turns `{[template]}` into `{\[template]}`. Unescape our annotation syntax.
-  const cleaned = result.replace(/\{\\\[([^\]]+)\]\}/g, '{[$1]}');
+  // remark-stringify backslash-escapes markdown-significant characters in
+  // text nodes (`[` to prevent link syntax, `:` for directives, `*`/`_` for
+  // emphasis, a literal `\` before punctuation, …). Our annotations are
+  // injected as plain text, so their interiors come back escaped. Undo that
+  // inside `{[…]}` template-annotation spans: removing one backslash from
+  // each backslash+punctuation pair (left to right) exactly inverts
+  // remark's escaping — including restoring an authored `\"` that remark
+  // doubled to `\\"`. The span regex understands quoted values, so a
+  // quoted `]` doesn't terminate the span.
+  let cleaned = result.replace(
+    ESCAPED_TEMPLATE_SPAN_RE,
+    (_m, inner: string) => `{[${unescapeMarkdownPunct(inner)}]}`,
+  );
+
+  // Same treatment for the trailing Pandoc `{…}` attribute block on heading
+  // lines (canonical emit order is Pandoc block then template annotation,
+  // so the span sits at end-of-line or just before a `{[…]}` span).
+  cleaned = cleaned.replace(HEADING_LINE_RE, (line) =>
+    line.replace(
+      TRAILING_ESCAPED_PANDOC_SPAN_RE,
+      (_m, inner: string) => `{${unescapeMarkdownPunct(inner)}}`,
+    ),
+  );
+
+  // remark-directive escapes `:` in text (since `:name` would round-trip as
+  // a text directive). Inside any other Pandoc-style `{…}` brace span, `:`
+  // is purely a value separator (e.g. `connectsTo=foo:flow`), so unescape
+  // it to keep round-trips lossless. The negative lookahead skips `{[…]}`
+  // template annotations — those are handled above.
+  cleaned = cleaned.replace(/\{(?!\\?\[)[^}]*\}/g, (match) => match.replace(/\\:/g, ':'));
 
   // Prepend YAML frontmatter if present
   if (doc.frontmatter && Object.keys(doc.frontmatter).length > 0) {

package/src/markdown/types.ts

@@ -126,6 +126,65 @@ export interface HeadingTemplateAnnotation {
   params?: Record<string, string>;
 }
 
+/**
+ * A directed connection from one block to another, parsed from a heading
+ * attribute `connectsTo=target1,target2:type,target3`. Mirrors the schema
+ * `BlockConnection` type — duplicated here so this module stays
+ * dependency-free from the doc schema.
+ */
+export interface BlockConnection {
+  /** Target block id. */
+  target: string;
+  /** Optional connection type/label (e.g., "flow", "requires"). */
+  type?: string;
+}
+
+/**
+ * Pandoc-style heading attribute block, parsed from `{#id .class key=value}`
+ * appearing at the end of a heading line (alongside, or instead of, the
+ * squisq-native `{[templateName …]}` block).
+ *
+ * @example
+ * ```markdown
+ * ## Architecture {#arch x=600 y=300 connectsTo=foo:flow,bar:requires}
+ * ```
+ * →
+ * ```ts
+ * {
+ *   id: 'arch',
+ *   params: { x: '600', y: '300', connectsTo: 'foo:flow,bar:requires' },
+ *   blockMeta: {
+ *     x: 600,
+ *     y: 300,
+ *     connectsTo: [{ target: 'foo', type: 'flow' }, { target: 'bar', type: 'requires' }],
+ *   },
+ * }
+ * ```
+ *
+ * `params` carries the raw pre-coercion strings (lossless for round-tripping),
+ * while `blockMeta` carries the typed values for known keys. Unknown keys flow
+ * to `metadata`.
+ */
+export interface HeadingAttributes {
+  /** Block id from `#identifier` (overrides slug-from-heading). */
+  id?: string;
+  /** Class tokens from `.classname` (reserved for downstream use). */
+  classes?: string[];
+  /** All key=value attributes as raw strings (lossless source for serialization). */
+  params?: Record<string, string>;
+  /** Typed values for known block-meta keys (coerced from `params`). */
+  blockMeta?: {
+    x?: number;
+    y?: number;
+    startTime?: number;
+    duration?: number;
+    connectsTo?: BlockConnection[];
+    transition?: import('../schemas/Transitions.js').Transition;
+  };
+  /** Subset of `params` whose keys are NOT in the known-key registry. */
+  metadata?: Record<string, string>;
+}
+
 /**
  * ATX or setext heading (# Heading).
  */
@@ -142,6 +201,13 @@ export interface MarkdownHeading extends MarkdownNodeBase {
    * stringification, so it round-trips transparently.
    */
   templateAnnotation?: HeadingTemplateAnnotation;
+  /**
+   * Pandoc-style heading attributes parsed from trailing `{#id .class key=value}`
+   * syntax. Independent from `templateAnnotation` — both may appear on the
+   * same heading in either order. Stripped from `children` during parsing
+   * and re-injected during stringification.
+   */
+  attributes?: HeadingAttributes;
 }
 
 /**

package/src/markdown/utils.ts

@@ -5,7 +5,8 @@
  * All functions are pure and operate on the JSON node interfaces.
  */
 
-import type { MarkdownNode, MarkdownDocument } from './types.js';
+import type { MarkdownNode, MarkdownDocument, HtmlNode } from './types.js';
+import { parseHtmlToNodes } from './htmlParse.js';
 
 /**
  * Get the children of any markdown node, if it has children.
@@ -162,6 +163,12 @@ 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);
+  // A single-line JSON object/array literal round-trips verbatim through
+  // the line-based `parseFrontmatter` (no leading quote to strip, no
+  // newline to split on), so write it unquoted to keep it human-readable
+  // — matching how `stringifyMarkdown` emits string values. Used by the
+  // compact custom-layouts payload.
+  if (/^[{[]/.test(value) && !/[\r\n]/.test(value)) return value;
   // Quote when needed: leading/trailing whitespace, leading punctuation that
   // could trigger YAML modes, or values that look like reserved literals.
   const needsQuote =
@@ -326,3 +333,44 @@ export function readFrontmatterThemeId(
   }
   return undefined;
 }
+
+/**
+ * Project an inline-HTML string (as stored on `TextLayer.content.html`) down
+ * to plain text — the value mirrored into `content.text` for plain consumers
+ * (PDF/markdown export, search, accessibility) and the SVG `<text>` fallback.
+ *
+ * `<br>` and block-level tags (`p`, `div`, `h1`–`h6`, `li`, `blockquote`,
+ * `pre`) become line breaks so multi-line rich content reads sensibly. Entity
+ * decoding is handled by {@link parseHtmlToNodes} (parse5-backed), so this is
+ * more correct than a regex tag-stripper.
+ */
+export function plainTextFromInlineHtml(html: string): string {
+  const BLOCK = new Set([
+    'p',
+    'div',
+    'h1',
+    'h2',
+    'h3',
+    'h4',
+    'h5',
+    'h6',
+    'li',
+    'blockquote',
+    'pre',
+  ]);
+  const walk = (nodes: HtmlNode[]): string =>
+    nodes
+      .map((n) => {
+        if (n.type === 'htmlText') return n.value;
+        if (n.type !== 'htmlElement') return '';
+        const tag = n.tagName.toLowerCase();
+        if (tag === 'br') return '\n';
+        const inner = walk(n.children);
+        return BLOCK.has(tag) ? `${inner}\n` : inner;
+      })
+      .join('');
+  return walk(parseHtmlToNodes(html))
+    .replace(/\u00A0/g, ' ')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}

package/src/recommend/templates.ts

@@ -251,6 +251,30 @@ function recommendedNamesForProfile(profile: BlockContentProfile): string[] {
   return Array.from(names);
 }
 
+/**
+ * Deterministic single-template choice for an unannotated heading block,
+ * from strong content signals only. Returns `undefined` when no signal is
+ * decisive — the caller keeps its structural default (`sectionHeader`).
+ *
+ * Precedence favors the most specific/structured content: a table beats
+ * an image beats a blockquote beats a stat-looking line. `blockIndex`
+ * alternates left/right feature composition for single-image blocks so a
+ * run of image sections doesn't stack the same layout.
+ *
+ * Used by `markdownToDoc`'s auto template picking (see its `autoTemplates`
+ * option); the multi-candidate `recommendTemplatesForBlock` below serves
+ * the editor's template-picker UI instead.
+ */
+export function pickAutoTemplate(profile: BlockContentProfile, blockIndex = 0): string | undefined {
+  if (profile.hasTable) return 'dataTable';
+  if (profile.imageCount >= 2) return 'photoGrid';
+  if (profile.hasImage) return blockIndex % 2 === 0 ? 'leftFeature' : 'rightFeature';
+  if (profile.hasBlockquote) return 'quote';
+  if (profile.hasNumberHighlight) return 'statHighlight';
+  if (profile.hasList) return 'list';
+  return undefined;
+}
+
 /**
  * Split a flat list of template names into a "Recommended" bucket
  * (matches the active block's content profile) and a "rest" bucket

package/src/schemas/BlockTemplates.ts

@@ -20,7 +20,7 @@
  * - imageWithCaption: Image with text overlay
  */
 
-import type { Layer, Block, Transition, MapTileStyle, MapMarker } from './Doc.js';
+import type { Layer, Block, Transition, MapTileStyle, MapMarker, MarkerStyle } from './Doc.js';
 import type { ViewportConfig, ViewportOrientation } from './Viewport.js';
 import type { LayoutHints } from './LayoutStrategy.js';
 import type { Theme } from './Theme.js';
@@ -110,6 +110,12 @@ interface BaseTemplateBlock {
    * Used with sourceStartTime to precisely position the block.
    */
   sourceDuration?: number;
+  /**
+   * Per-block override for the theme's photographic image grade
+   * (`theme.style.imageTreatment`). `'none'` opts this block's imagery out;
+   * a treatment type forces that grade regardless of the theme.
+   */
+  imageTreatment?: 'none' | 'mono' | 'duotone' | 'warm' | 'cool';
 }
 
 /**
@@ -470,6 +476,78 @@ export interface VideoPullQuoteInput extends BaseTemplateBlock {
   };
 }
 
+/**
+ * Diagram block - renders child headings as a node-and-edge diagram.
+ *
+ * Unlike other templates, the diagram template reads its content from
+ * the parent block's `children` (passed via `context.children`) — each
+ * child heading becomes a node, positioned by its `x`/`y` and connected
+ * by its `connectsTo`. Per-diagram options on this input control overall
+ * appearance; per-node data lives on the child blocks themselves.
+ */
+export interface DiagramBlockInput extends BaseTemplateBlock {
+  template: 'diagram';
+  /** Optional diagram title displayed above the canvas. */
+  title?: string;
+  /** Color scheme for nodes and edges. */
+  colorScheme?: ColorScheme;
+  /** Node shape style (default: 'rounded'). */
+  nodeShape?: 'rounded' | 'rect' | 'pill';
+  /** Edge routing (default: 'curved'). */
+  edgeStyle?: 'curved' | 'straight' | 'orthogonal';
+  /** Marker at each edge's start (default: 'none'). */
+  startStyle?: MarkerStyle;
+  /** Marker at each edge's end (default: 'arrow'). */
+  endStyle?: MarkerStyle;
+  /** Edge line style (default: 'solid'). */
+  lineStyle?: 'solid' | 'dashed' | 'dotted';
+}
+
+/**
+ * Free-form 2D canvas block (`layout`). Like `drawing`/`diagram`, the
+ * `layout` template is a children-driven container: each child heading is
+ * one absolutely-positioned layer (`{[text …]}` / `{[rectangle …]}` /
+ * `{[image …]}`), read from `context.children`. A text box's content is the
+ * child's body markdown. Backed by the `layoutBlock` template.
+ *
+ * (Legacy documents stored layers as a base64-JSON `layers=` param on the
+ * heading; the editor auto-migrates those to child sub-blocks on first edit.)
+ */
+export interface RawLayersInput extends BaseTemplateBlock {
+  template: 'layout';
+}
+
+/**
+ * Drawing block — renders child headings as free-form shapes on a canvas.
+ *
+ * Like `diagram`, the drawing template reads its content from the parent
+ * block's `children` (passed via `context.children`). Each child heading
+ * is a shape: its `{[shape …]}` annotation names the primitive
+ * (`rectangle`/`rect`, `circle`, `line`, `arrow`, `path`, `text`) and
+ * carries geometry/style as params; its `{#id}` makes it referenceable;
+ * its heading text is the shape label and its body text an optional
+ * sublabel. Connectors (`line`/`arrow` with `from`/`to`) join shapes by id.
+ *
+ * Coordinates are author-defined units; the template fits the bounding box
+ * of all shapes to the viewport (same scaling as `diagram`), so authors
+ * don't have to think in absolute pixels.
+ *
+ * Legacy drawings authored visually persist their `Layer[]` as a base64
+ * `layers="…"` Pandoc param instead of children; the template decodes and
+ * returns those directly when no children are present (see `drawingBlock`).
+ */
+export interface DrawingBlockInput extends BaseTemplateBlock {
+  template: 'drawing';
+  /** Optional title displayed above the canvas. */
+  title?: string;
+  /** Color scheme for shapes that don't pin their own fill/stroke. */
+  colorScheme?: ColorScheme;
+  /** Default fill for shapes that don't specify one (default: 'none'). */
+  fill?: string;
+  /** Default stroke for shapes that don't specify one (default: theme text). */
+  stroke?: string;
+}
+
 /**
  * Data table - renders a themed table with headers and rows.
  * Ideal for structured data, comparisons, and reference information.
@@ -511,7 +589,10 @@ export type TemplateBlock =
   | PullQuoteInput
   | VideoWithCaptionInput
   | VideoPullQuoteInput
-  | DataTableInput;
+  | DataTableInput
+  | DiagramBlockInput
+  | DrawingBlockInput
+  | RawLayersInput;
 
 /**
  * A block can be either a raw Block or a TemplateBlock.
@@ -548,6 +629,20 @@ export interface TemplateContext {
   orientation: ViewportOrientation;
   /** Layout hints for this orientation */
   layout: LayoutHints;
+  /**
+   * The block's direct children (set by `getLayers` when the block has
+   * `children`). Most templates ignore this; aggregate templates like
+   * `diagram` consume it to render each child as part of their output.
+   */
+  children?: Block[];
+  /**
+   * The source block being expanded. Used by user-defined custom
+   * templates so the token resolver can substitute `{title}`,
+   * `{content}`, `{children}`, and `{image:N}` against the block's
+   * data at render time. Built-in templates ignore this and rely on
+   * their typed `input` parameters instead.
+   */
+  block?: Block;
 }
 
 /**
@@ -560,6 +655,10 @@ export function createTemplateContext(
   viewport: ViewportConfig = VIEWPORT_PRESETS.landscape,
 ): TemplateContext {
   const orientation = getViewportOrientation(viewport);
+  // Theme renderStyle may override individual layout hints (e.g. a theme
+  // that wants a lower primaryY across every template).
+  const overrides = theme.renderStyle.layoutOverrides;
+  const baseLayout = getLayoutHints(orientation);
   return {
     theme,
     blockIndex,
@@ -567,7 +666,7 @@ export function createTemplateContext(
     viewport,
     fontScale: calculateFontScale(viewport),
     orientation,
-    layout: getLayoutHints(orientation),
+    layout: overrides ? { ...baseLayout, ...overrides } : baseLayout,
   };
 }
 
@@ -647,7 +746,9 @@ export type PersistentLayerTemplateType =
   | 'solidBackground' // Solid color fill
   | 'gradientBackground' // CSS gradient or preset
   | 'imageBackground' // Blurred/faded hero image
-  | 'patternBackground' // Subtle pattern (dots, grid)
+  | 'patternBackground' // Subtle pattern (dots, grid, diagonal, noise/grain)
+  | 'vignette' // Soft radial edge darkening (top layer)
+  | 'ambientGradient' // Slowly drifting surface gradient (bottom layer)
   | 'titleCaption' // Article title in corner
   | 'cornerBranding' // Logo or text badge
   | 'progressIndicator'; // Bar/dots showing position
@@ -660,6 +761,8 @@ export type PersistentLayerTemplateConfig =
   | GradientBackgroundConfig
   | ImageBackgroundConfig
   | PatternBackgroundConfig
+  | VignetteConfig
+  | AmbientGradientConfig
   | TitleCaptionConfig
   | CornerBrandingConfig
   | ProgressIndicatorConfig;
@@ -718,6 +821,32 @@ export interface PatternBackgroundConfig {
   scale?: number;
 }
 
+/**
+ * Soft radial vignette (top layer) — transparent center darkening toward
+ * the frame edges. The classic film-look framing device.
+ */
+export interface VignetteConfig {
+  type: 'vignette';
+  /** Edge darkness 0-1 (default 0.3). */
+  strength?: number;
+  /** Vignette color (default black). */
+  color?: string;
+}
+
+/**
+ * Slowly drifting surface gradient (bottom layer). Colors default to the
+ * theme's surface family at expansion time.
+ */
+export interface AmbientGradientConfig {
+  type: 'ambientGradient';
+  /** Gradient start color. */
+  from?: string;
+  /** Gradient end color. */
+  to?: string;
+  /** Drift loop duration in seconds (default 40). */
+  duration?: number;
+}
+
 // ============================================
 // Overlay Layer Configs
 // ============================================

package/src/schemas/CustomTemplates.ts

@@ -0,0 +1,74 @@
+/**
+ * Custom Templates Schema
+ *
+ * User-defined block layout templates. The author designs a visual
+ * layout once (in the editor's TemplateDesigner) and saves it as a
+ * `CustomTemplateDefinition`. The definition lives either in the
+ * document's frontmatter (per-doc, portable, ships with the markdown)
+ * or in the user's local library (cross-doc reuse via localStorage).
+ *
+ * A custom template's content is just a `Layer[]` — the same shape that
+ * built-in templates emit at expansion time. The novel bit is
+ * *placeholder tokens*: TextLayer / ImageLayer content fields may carry
+ * strings like `{title}`, `{content}`, `{children}`, or `{image:N}`
+ * that the resolver (see `doc/templates/tokens/resolveTokens.ts`)
+ * substitutes against the source Block at render time.
+ *
+ * Responsiveness model: every numeric position field in `layers` is
+ * stored as a `%`-string relative to `viewport`, so the same template
+ * renders correctly at any of Squisq's viewport presets (landscape,
+ * portrait, square). The `viewport` field itself is purely an
+ * authoring-time reference — it tells the designer canvas which aspect
+ * ratio to mount with, and the thumbnail renderer which viewBox to use.
+ */
+
+import type { Layer } from './Doc.js';
+
+/**
+ * A single user-defined template. Stored in `Doc.customTemplates`
+ * (frontmatter-backed) or in the user's local library.
+ */
+export interface CustomTemplateDefinition {
+  /**
+   * Stable id used in heading annotations (`### Foo {[name]}`). Must be
+   * a slug — lowercase alphanumerics, hyphens. The picker enforces
+   * uniqueness within a (doc + library) merged namespace.
+   */
+  name: string;
+
+  /** Human-readable label shown in the template picker. */
+  label: string;
+
+  /** Optional one-sentence description for the picker card. */
+  description?: string;
+
+  /**
+   * Authoring viewport — the canvas size the designer drew against.
+   * Stored so the designer and thumbnail renderer can reproduce the
+   * same canvas. Layer positions are stored as `%`-strings, so the
+   * actual render-time viewport can differ from this without breaking
+   * the layout. Defaults to 1920×1080 landscape.
+   */
+  viewport: {
+    width: number;
+    height: number;
+  };
+
+  /**
+   * The visual content. Every `position.x` / `position.y` /
+   * `position.width` / `position.height` should be a `%`-string at
+   * save time (the designer's normalizePositions step enforces this).
+   *
+   * Tokens supported in v1:
+   *   - TextLayer.content.text — `{title}`, `{content}`, `{children}`,
+   *     `{image:N}` (substitutes the Nth image's alt text)
+   *   - ImageLayer.content.src — `{image:N}` (substitutes the URL)
+   */
+  layers: Layer[];
+}
+
+/**
+ * Tag value for the YAML frontmatter key that carries inlined custom
+ * template definitions. Exported so the markdown bridge stays in sync.
+ */
+export const FRONTMATTER_CUSTOM_TEMPLATES_KEY = 'squisq-custom-templates';