@bendyline/squisq 1.5.1 → 1.5.2

package/dist/story/index.d.ts

@@ -516,9 +516,11 @@ declare function drawingBlock(input: DrawingBlockInput, context: TemplateContext
  *  - `markerPath(style, dir)` → the `<marker>` path for a line end-style, in the
  *    standard 0–10 marker viewBox (shared by the SSR `PathLayer` renderer and the
  *    editor's edge renderer).
- *  - `connectorPath(routing, start, end)` + `clipEndpoints(a, b)` → the line/edge
+ *  - `connectorPath(routing, start, end)` + `snapEndpoints(a, b)` → the line/edge
  *    geometry between two shapes (straight / orthogonal / curved), lifted from the
- *    diagram template so drawings and diagrams draw identical connectors.
+ *    diagram template so drawings and diagrams draw identical connectors. The older
+ *    `clipEndpoints(a, b)` helper remains for free-angle clipping, but rendered
+ *    connectors use snapped ports so authored lines land on stable attachment points.
  */
 
 /** Connector routing styles. */
@@ -549,6 +551,12 @@ interface ClipBox {
     rx: number;
     ry: number;
 }
+type ConnectorPort = 'top' | 'right' | 'bottom' | 'left' | 'top-left' | 'top-right' | 'bottom-right' | 'bottom-left';
+interface ConnectorSnapPoint {
+    port: ConnectorPort;
+    x: number;
+    y: number;
+}
 /** Intersection of the center-to-center line with `from`'s bounding box. */
 declare function clipPoint(from: ClipBox, to: ClipBox): {
     x: number;
@@ -565,6 +573,22 @@ declare function clipEndpoints(a: ClipBox, b: ClipBox): {
         y: number;
     };
 };
+/** The stable connector ports exposed around a shape/card box. */
+declare function snapPoints(box: ClipBox): ConnectorSnapPoint[];
+/** Nearest stable connector port on `box` to an arbitrary point. */
+declare function nearestSnapPoint(box: ClipBox, point: {
+    x: number;
+    y: number;
+}): ConnectorSnapPoint;
+/**
+ * Pick the pair of connector ports, one on each box, with the shortest
+ * distance between them. This gives stable attachments to side/corner handles
+ * instead of arbitrary center-ray intersections.
+ */
+declare function snapEndpoints(a: ClipBox, b: ClipBox): {
+    start: ConnectorSnapPoint;
+    end: ConnectorSnapPoint;
+};
 /** Build the SVG `d` for a connector between two clipped endpoints. */
 declare function connectorPath(routing: ConnectorRouting, start: {
     x: number;
@@ -1774,4 +1798,4 @@ declare function coerceTemplateParams(template: string | undefined, params: Reco
  */
 declare function lintTemplateParams(template: string, params: Record<string, string>): TemplateParamFinding[];
 
-export { type AccentLayout, type AudioSegmentTiming, BASE_INPUT_DESCRIPTORS, CONTAINER_TEMPLATES, type ClipBox, type ConnectorRouting, type CoverBlockInput, DEFAULT_LAYOUT, type DataFenceParseResult, type DeriveTemplateInputsOptions, type DiagramEdge, type DiagramLayout, type DiagramLayoutOptions, type DiagramNodePosition, DocBlock, type DocStylePreset, type DrawingConnector, type DrawingLayout, type DrawingLayoutOptions, type DrawingShape, type DrawingShapeKind, type ExpandDocBlocksOptions, type ExtractedTableData, type FirstImage, type InputCoercion, type LayoutLayerDefaults, type LayoutLayersResult, type MarkdownToDocOptions, type MarkdownValidationResult, PATH_SHAPE_KINDS, PersistentLayerConfig, type RenderContext, type RuntimeTemplateRegistry, SHAPE_NAMES, TEMPLATE_ALIASES, TEMPLATE_INPUT_DESCRIPTORS, TEMPLATE_METADATA, TemplateBlock, TemplateContext, type TemplateInputDescriptor, type TemplateMetadata, type TemplateParamFinding, Theme, ThemeColorScheme, type ValidateOptions, ViewportConfig, adjustY, applyRenderStyleToLayers, buildRegistry, clipEndpoints, clipPoint, coerceTemplateParams, comparisonBar, computeDiagramLayout, computeDrawingLayout, computeLayoutLayers, connectorPath, countBlocks, coverBlock, createAccentLayers, cssFilterForTreatment, dataTable, dateEvent, decodeLayersFromFrontmatter, definitionCard, deriveTemplateInputs, diagramBlock, docToMarkdown, drawingBlock, encodeLayersForFrontmatter, expandCoverBlock, expandDocBlocks, expandPersistentLayers, expandTemplateBlock, extractBlockquoteText, extractBodyPlainText, extractFirstImage, extractImages, extractListItems, extractTableData, extractTableFromContents, factCard, fallbackBlockLayers, findFirstTable, flattenBlocks, flattenRenderableBlocks, fullBleedQuote, getAccentLayout, getAnimationProgress, getAnimationStyle, getAvailableTemplates, getBlockDepth, getDefaultAnimation, getDefaultAnimationDuration, getDocStyleConfig, getLayers, getOverlayOpacity, getPersistentLayersFromTheme, getTemplateHint, getThemeFont, getTransitionClass, hasTemplate, imageWithCaption, isContainerTemplate, isDataFence, isShapeName, layoutBlock, leftFeature, lineStyleDasharray, lintTemplateParams, listBlock, mapBlock, markdownToDoc, markerPath, normalizeShapeKind, parseDataFence, parseYamlSubset, photoGrid, pullQuote, quoteBlock, readCustomTemplatesFromFrontmatter, readCustomThemesFromFrontmatter, replaceDataFence, resolveAudioMapping, resolveColorScheme, resolvePersistentLayers, resolveTemplateName, resolveThemeForDoc, rightFeature, scaleAnimationDuration, scoreTextSimilarity, sectionHeader, shapePath, shouldUseShadow, statHighlight, templateRegistry, themeWantsAmbientMotion, themedEntrance, themedFontSize, themedImageTreatment, themedScrim, themedSurfaceGradient, titleBlock, twoColumn, validateMarkdownDoc, validateMarkdownSource, videoPullQuote, videoWithCaption, wrapWithPersistentLayers, writeCustomTemplatesToFrontmatter, writeCustomThemesToFrontmatter };
+export { type AccentLayout, type AudioSegmentTiming, BASE_INPUT_DESCRIPTORS, CONTAINER_TEMPLATES, type ClipBox, type ConnectorPort, type ConnectorRouting, type ConnectorSnapPoint, type CoverBlockInput, DEFAULT_LAYOUT, type DataFenceParseResult, type DeriveTemplateInputsOptions, type DiagramEdge, type DiagramLayout, type DiagramLayoutOptions, type DiagramNodePosition, DocBlock, type DocStylePreset, type DrawingConnector, type DrawingLayout, type DrawingLayoutOptions, type DrawingShape, type DrawingShapeKind, type ExpandDocBlocksOptions, type ExtractedTableData, type FirstImage, type InputCoercion, type LayoutLayerDefaults, type LayoutLayersResult, type MarkdownToDocOptions, type MarkdownValidationResult, PATH_SHAPE_KINDS, PersistentLayerConfig, type RenderContext, type RuntimeTemplateRegistry, SHAPE_NAMES, TEMPLATE_ALIASES, TEMPLATE_INPUT_DESCRIPTORS, TEMPLATE_METADATA, TemplateBlock, TemplateContext, type TemplateInputDescriptor, type TemplateMetadata, type TemplateParamFinding, Theme, ThemeColorScheme, type ValidateOptions, ViewportConfig, adjustY, applyRenderStyleToLayers, buildRegistry, clipEndpoints, clipPoint, coerceTemplateParams, comparisonBar, computeDiagramLayout, computeDrawingLayout, computeLayoutLayers, connectorPath, countBlocks, coverBlock, createAccentLayers, cssFilterForTreatment, dataTable, dateEvent, decodeLayersFromFrontmatter, definitionCard, deriveTemplateInputs, diagramBlock, docToMarkdown, drawingBlock, encodeLayersForFrontmatter, expandCoverBlock, expandDocBlocks, expandPersistentLayers, expandTemplateBlock, extractBlockquoteText, extractBodyPlainText, extractFirstImage, extractImages, extractListItems, extractTableData, extractTableFromContents, factCard, fallbackBlockLayers, findFirstTable, flattenBlocks, flattenRenderableBlocks, fullBleedQuote, getAccentLayout, getAnimationProgress, getAnimationStyle, getAvailableTemplates, getBlockDepth, getDefaultAnimation, getDefaultAnimationDuration, getDocStyleConfig, getLayers, getOverlayOpacity, getPersistentLayersFromTheme, getTemplateHint, getThemeFont, getTransitionClass, hasTemplate, imageWithCaption, isContainerTemplate, isDataFence, isShapeName, layoutBlock, leftFeature, lineStyleDasharray, lintTemplateParams, listBlock, mapBlock, markdownToDoc, markerPath, nearestSnapPoint, normalizeShapeKind, parseDataFence, parseYamlSubset, photoGrid, pullQuote, quoteBlock, readCustomTemplatesFromFrontmatter, readCustomThemesFromFrontmatter, replaceDataFence, resolveAudioMapping, resolveColorScheme, resolvePersistentLayers, resolveTemplateName, resolveThemeForDoc, rightFeature, scaleAnimationDuration, scoreTextSimilarity, sectionHeader, shapePath, shouldUseShadow, snapEndpoints, snapPoints, statHighlight, templateRegistry, themeWantsAmbientMotion, themedEntrance, themedFontSize, themedImageTreatment, themedScrim, themedSurfaceGradient, titleBlock, twoColumn, validateMarkdownDoc, validateMarkdownSource, videoPullQuote, videoWithCaption, wrapWithPersistentLayers, writeCustomTemplatesToFrontmatter, writeCustomThemesToFrontmatter };

package/dist/story/index.js

@@ -105,7 +105,7 @@ import {
   wrapWithPersistentLayers,
   writeCustomTemplatesToFrontmatter,
   writeCustomThemesToFrontmatter
-} from "../chunk-LH7I6SH7.js";
+} from "../chunk-5TYS5V3G.js";
 import "../chunk-UY7KGQ5R.js";
 import "../chunk-V543AI2F.js";
 import "../chunk-FVTQSNR7.js";
@@ -116,8 +116,11 @@ import {
   connectorPath,
   lineStyleDasharray,
   markerPath,
-  shapePath
-} from "../chunk-RUDYOTA6.js";
+  nearestSnapPoint,
+  shapePath,
+  snapEndpoints,
+  snapPoints
+} from "../chunk-LTN6I7QW.js";
 import {
   DEFAULT_THEME,
   FRONTMATTER_CUSTOM_TEMPLATES_KEY,
@@ -136,7 +139,7 @@ import {
   isTemplateBlock,
   scaledFontSize2 as scaledFontSize
 } from "../chunk-DLXZMS5K.js";
-import "../chunk-TEEEILMP.js";
+import "../chunk-BEQODJWV.js";
 import "../chunk-HWVFJAAH.js";
 import "../chunk-DBS6RIFL.js";
 import "../chunk-QE7TWGVT.js";
@@ -230,6 +233,7 @@ export {
   mapBlock,
   markdownToDoc,
   markerPath,
+  nearestSnapPoint,
   normalizeShapeKind,
   parseDataFence,
   parseYamlSubset,
@@ -252,6 +256,8 @@ export {
   sectionHeader,
   shapePath,
   shouldUseShadow,
+  snapEndpoints,
+  snapPoints,
   statHighlight,
   templateRegistry,
   themeWantsAmbientMotion,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/squisq",
-  "version": "1.5.1",
+  "version": "1.5.2",
   "description": "Headless utilities for doc/block rendering, spatial math, Markdown, and storage",
   "license": "MIT",
   "author": "Bendyline",

package/src/__tests__/coverBlock.test.ts

@@ -85,6 +85,7 @@ describe('coverBlock with hero image', () => {
   it('does not produce theme background layers', () => {
     const layers = coverBlock(input, landscapeContext);
     expect(findLayer(layers, 'cover-bg')).toBeUndefined();
+    expect(findLayer(layers, 'cover-bg-tint')).toBeUndefined();
     expect(findLayer(layers, 'cover-accent')).toBeUndefined();
   });
 
@@ -110,12 +111,16 @@ describe('coverBlock without hero image', () => {
     subtitle: 'Subtitle text',
   };
 
-  it('produces theme background instead of hero', () => {
+  it('produces theme background and soft tint instead of hero', () => {
     const layers = coverBlock(input, landscapeContext);
     const bg = findShape(layers, 'cover-bg');
+    const tint = findShape(layers, 'cover-bg-tint');
     expect(bg).toBeDefined();
     expect(bg!.type).toBe('shape');
-    expect(bg!.content.fill).toContain('radial-gradient');
+    expect(bg!.content.fill).toBe(DEFAULT_THEME.colors.background);
+    expect(tint).toBeDefined();
+    expect(tint!.content.fill).toContain('radial-gradient');
+    expect(tint!.content.fill).toContain('rgba(37, 99, 235, 0.16)');
   });
 
   it('produces decorative accent line', () => {
@@ -144,6 +149,31 @@ describe('coverBlock without hero image', () => {
     const subtitle = findLayer(layers, 'cover-subtitle');
     expect(subtitle!.position.y).not.toBe('82%');
   });
+
+  it('uses high-contrast Standard Light cover text', () => {
+    const layers = coverBlock(input, landscapeContext);
+    const title = findText(layers, 'cover-title');
+    const subtitle = findText(layers, 'cover-subtitle');
+    expect(title!.content.style.shadow).toBe(false);
+    expect(subtitle!.content.style.fontWeight).toBe('bold');
+    expect(subtitle!.content.style.color).toBe('rgba(15, 23, 42, 0.78)');
+  });
+
+  it('keeps non-Standard themes on the existing dramatic cover background', () => {
+    const nonStandardContext = createTemplateContext(
+      { ...DEFAULT_THEME, id: 'custom-light' },
+      0,
+      1,
+      VIEWPORT_PRESETS.landscape,
+    );
+    const layers = coverBlock(input, nonStandardContext);
+    const bg = findShape(layers, 'cover-bg');
+    const title = findText(layers, 'cover-title');
+    expect(findShape(layers, 'cover-bg-tint')).toBeUndefined();
+    expect(bg!.content.fill).toContain('radial-gradient');
+    expect(bg!.content.fill).toContain(`${DEFAULT_THEME.colors.primary} 0%`);
+    expect(title!.content.style.shadow).toBe(true);
+  });
 });
 
 // ── coverBlock title-only (no subtitle) ─────────────────────────────
@@ -273,6 +303,7 @@ describe('expandCoverBlock', () => {
     const config: StartBlockConfig = { title: 'No Hero' };
     const layers = expandCoverBlock(config, landscapeContext);
     expect(layers.some((l) => l.id === 'cover-bg')).toBe(true);
+    expect(layers.some((l) => l.id === 'cover-bg-tint')).toBe(true);
     expect(layers.some((l) => l.id === 'cover-title')).toBe(true);
     expect(layers.some((l) => l.id === 'cover-hero')).toBe(false);
   });

package/src/__tests__/markdownToDoc.test.ts

@@ -394,14 +394,15 @@ describe('template annotation in markdownToDoc', () => {
     expect(output).toContain('{[factCard style=minimal]}');
   });
 
-  it('docToMarkdown injects transition attributes from block metadata', () => {
+  it('docToMarkdown injects transition params into the squiggly annotation', () => {
     const md = parseMarkdown('## Section\n\nBody');
     const doc = markdownToDoc(md);
     doc.blocks[0].transition = { type: 'wipe', duration: 0.8, direction: 'left' };
 
     const output = stringifyMarkdown(docToMarkdown(doc));
 
-    expect(output).toContain('{transition=wipe transitionDuration=0.8 transitionDirection=left}');
+    expect(output).toContain('{[transition=wipe transitionDuration=0.8 transitionDirection=left]}');
+    expect(output).not.toContain('{transition=wipe');
   });
 
   it('a programmatic transition survives the string round trip', () => {
@@ -445,6 +446,8 @@ describe('template annotation in markdownToDoc', () => {
 
     const output = stringifyMarkdown(docToMarkdown(doc));
     expect(output).toContain('transition=wipe');
+    expect(output).toContain('{[transition=wipe transitionDirection=left]}');
+    expect(output).not.toContain('{transition=wipe');
     const reparsed = markdownToDoc(parseMarkdown(output));
     expect(reparsed.blocks[0].transition).toEqual({ type: 'wipe', direction: 'left' });
   });

package/src/__tests__/shapeGeometry.test.ts

@@ -4,8 +4,11 @@ import {
   markerPath,
   connectorPath,
   clipEndpoints,
+  nearestSnapPoint,
   lineStyleDasharray,
   PATH_SHAPE_KINDS,
+  snapEndpoints,
+  snapPoints,
 } from '../doc/utils/shapeGeometry.js';
 
 describe('shapePath', () => {
@@ -79,6 +82,40 @@ describe('clipEndpoints', () => {
   });
 });
 
+describe('snapEndpoints', () => {
+  const a = { cx: 50, cy: 50, rx: 30, ry: 20 };
+  const b = { cx: 180, cy: 50, rx: 30, ry: 20 };
+
+  it('exposes side and corner ports around a box', () => {
+    expect(snapPoints(a).map((p) => p.port)).toEqual([
+      'top',
+      'right',
+      'bottom',
+      'left',
+      'top-left',
+      'top-right',
+      'bottom-right',
+      'bottom-left',
+    ]);
+  });
+
+  it('snaps horizontal connections to side ports', () => {
+    const r = snapEndpoints(a, b);
+    expect(r.start).toMatchObject({ port: 'right', x: 80, y: 50 });
+    expect(r.end).toMatchObject({ port: 'left', x: 150, y: 50 });
+  });
+
+  it('snaps diagonal connections to nearest corner ports', () => {
+    const r = snapEndpoints(a, { cx: 180, cy: 140, rx: 30, ry: 20 });
+    expect(r.start).toMatchObject({ port: 'bottom-right', x: 80, y: 70 });
+    expect(r.end).toMatchObject({ port: 'top-left', x: 150, y: 120 });
+  });
+
+  it('finds the nearest port toward a free pointer', () => {
+    expect(nearestSnapPoint(a, { x: 100, y: 10 }).port).toBe('top-right');
+  });
+});
+
 describe('lineStyleDasharray', () => {
   it('maps line styles to dash patterns', () => {
     expect(lineStyleDasharray('dashed')).toBe('8 6');

package/src/doc/docToMarkdown.ts

@@ -39,6 +39,8 @@ import {
   writeCustomThemesToFrontmatter,
 } from './customThemesFrontmatter.js';
 
+const TRANSITION_PARAM_KEYS = ['transition', 'transitionDuration', 'transitionDirection'] as const;
+
 /**
  * Convert a Doc with heading-driven blocks back to a MarkdownDocument.
  *
@@ -134,64 +136,81 @@ function synthesizeAnnotationParagraph(block: Block): MarkdownParagraph {
  * template and templateOverrides. Returns a (possibly cloned) heading.
  */
 function ensureAnnotation(block: Block, heading: MarkdownHeading): MarkdownHeading {
-  const attrs = ensureTransitionAttributes(block, heading);
+  const { attributes, transitionParams } = ensureTransitionMetadata(block, heading);
 
   // If the block has a non-default template or overrides, inject an annotation
   const hasExplicitTemplate =
     block.template && block.template !== 'sectionHeader' && block.autoTemplate !== true;
   const hasOverrides = block.templateOverrides && Object.keys(block.templateOverrides).length > 0;
 
-  // If the heading already has an annotation, trust it (it came from parsing).
-  // Transition attrs may still have been injected above if the block changed.
-  if (heading.templateAnnotation) {
-    return attrs === heading.attributes ? heading : { ...heading, attributes: attrs };
+  let templateAnnotation = heading.templateAnnotation;
+  if (!templateAnnotation && (hasExplicitTemplate || hasOverrides || transitionParams)) {
+    templateAnnotation = {
+      ...(hasExplicitTemplate ? { template: block.template ?? 'sectionHeader' } : {}),
+      ...(hasOverrides ? { params: block.templateOverrides } : {}),
+    };
   }
 
-  if (!hasExplicitTemplate && !hasOverrides) {
-    return attrs === heading.attributes ? heading : { ...heading, attributes: attrs };
+  if (transitionParams) {
+    templateAnnotation = {
+      ...(templateAnnotation ?? {}),
+      params: {
+        ...(templateAnnotation?.params ?? {}),
+        ...transitionParams,
+      },
+    };
   }
 
-  // Clone to avoid mutating the original
-  return {
-    ...heading,
-    children: [...heading.children],
-    attributes: attrs,
-    templateAnnotation: {
-      template: block.template ?? 'sectionHeader',
-      ...(hasOverrides ? { params: block.templateOverrides } : {}),
-    },
-  };
+  if (attributes === heading.attributes && templateAnnotation === heading.templateAnnotation) {
+    return heading;
+  }
+
+  return { ...heading, children: [...heading.children], attributes, templateAnnotation };
 }
 
-function ensureTransitionAttributes(
+function ensureTransitionMetadata(
   block: Block,
   heading: MarkdownHeading,
-): MarkdownHeading['attributes'] {
+): {
+  attributes: MarkdownHeading['attributes'];
+  transitionParams: Record<string, string> | undefined;
+} {
   const transition = block.transition;
-  if (!transition) return heading.attributes;
-
-  // The transition is deliberately written to BOTH channels, which serve
-  // different consumers:
-  // - `params` is what `stringifyMarkdown` serializes into the Pandoc `{…}`
-  //   attribute text (serializePandocAttributes reads only id/classes/params).
-  // - `blockMeta` is what `markdownToDoc` reads back directly (makeBlock,
-  //   pinnedHeadingMeta) — an in-memory Doc → MarkdownDocument → Doc round
-  //   trip never re-parses params, so a stale/missing `blockMeta.transition`
-  //   would lose or resurrect the wrong transition.
-  const attrs = heading.attributes ?? {};
-  return {
+  if (!transition) {
+    return { attributes: heading.attributes, transitionParams: undefined };
+  }
+
+  // The transition is written to the squisq-native `{[…]}` params for
+  // author-facing markdown, and to `attributes.blockMeta` for the in-memory
+  // Doc → MarkdownDocument → Doc path (which does not re-parse string params).
+  const attrs = removeTransitionParams(heading.attributes) ?? {};
+  const attributes = {
     ...attrs,
-    params: {
-      ...(attrs.params ?? {}),
+    blockMeta: {
+      ...(attrs.blockMeta ?? {}),
+      transition,
+    },
+  };
+  return {
+    attributes,
+    transitionParams: {
       transition: transition.type,
       ...(transition.duration !== undefined
         ? { transitionDuration: String(transition.duration) }
         : {}),
       ...(transition.direction ? { transitionDirection: transition.direction } : {}),
     },
-    blockMeta: {
-      ...(attrs.blockMeta ?? {}),
-      transition,
-    },
+  };
+}
+
+function removeTransitionParams(
+  attrs: MarkdownHeading['attributes'],
+): MarkdownHeading['attributes'] {
+  if (!attrs?.params) return attrs;
+  const params = { ...attrs.params };
+  for (const key of TRANSITION_PARAM_KEYS) delete params[key];
+  return {
+    ...attrs,
+    ...(Object.keys(params).length > 0 ? { params } : { params: undefined }),
   };
 }

package/src/doc/templates/coverBlock.ts

@@ -18,6 +18,7 @@ import type { Layer } from '../../schemas/Doc.js';
 import type { TemplateContext } from '../../schemas/BlockTemplates.js';
 import type { StartBlockConfig } from '../../schemas/Doc.js';
 import { getThemeFont, themedFontSize, themedImageTreatment } from '../utils/themeUtils.js';
+import { relativeLuminance, withAlpha } from '../../schemas/colorUtils.js';
 import { mapAmbientMotion } from './accentImage.js';
 
 /**
@@ -61,6 +62,11 @@ export function fitCoverTitleSize(title: string): number {
   return Math.max(COVER_TITLE_MIN_BASE_PX, Math.round(scaled));
 }
 
+function isStandardLightCover(context: TemplateContext): boolean {
+  const { theme } = context;
+  return theme.id === 'standard' && relativeLuminance(theme.colors.background) > 0.85;
+}
+
 /**
  * Generate cover block layers from StartBlockConfig.
  */
@@ -68,6 +74,7 @@ export function coverBlock(input: CoverBlockInput, context: TemplateContext): La
   const treatment = themedImageTreatment(context, input.imageTreatment);
   const { heroSrc, heroAlt, title, subtitle, ambientMotion, heroCredit, heroLicense } = input;
   const { theme, layout } = context;
+  const standardLightCover = !heroSrc && isStandardLightCover(context);
 
   // Scale font sizes for viewport - cover titles are larger than regular title blocks.
   // The cover title wraps within maxTextWidth but does not otherwise shrink, so a long
@@ -113,16 +120,42 @@ export function coverBlock(input: CoverBlockInput, context: TemplateContext): La
       },
     );
   } else {
-    // No hero image: use a rich theme-driven background with radial gradient
-    layers.push({
-      type: 'shape',
-      id: 'cover-bg',
-      content: {
-        shape: 'rect',
-        fill: `radial-gradient(ellipse at 50% 40%, ${theme.colors.primary} 0%, ${theme.colors.background} 100%)`,
-      },
-      position: { x: 0, y: 0, width: '100%', height: '100%' },
-    });
+    if (standardLightCover) {
+      // Standard Light needs a restrained cover-poster treatment; a
+      // full-strength primary radial hotspot overwhelms dark serif text
+      // and makes the subtitle muddy.
+      layers.push(
+        {
+          type: 'shape',
+          id: 'cover-bg',
+          content: {
+            shape: 'rect',
+            fill: theme.colors.background,
+          },
+          position: { x: 0, y: 0, width: '100%', height: '100%' },
+        },
+        {
+          type: 'shape',
+          id: 'cover-bg-tint',
+          content: {
+            shape: 'rect',
+            fill: `radial-gradient(ellipse at 50% 40%, ${withAlpha(theme.colors.primary, 0.16)} 0%, ${withAlpha(theme.colors.primary, 0.07)} 38%, ${withAlpha(theme.colors.primary, 0)} 78%)`,
+          },
+          position: { x: 0, y: 0, width: '100%', height: '100%' },
+        },
+      );
+    } else {
+      // Non-Standard themes keep the existing dramatic radial cover look.
+      layers.push({
+        type: 'shape',
+        id: 'cover-bg',
+        content: {
+          shape: 'rect',
+          fill: `radial-gradient(ellipse at 50% 40%, ${theme.colors.primary} 0%, ${theme.colors.background} 100%)`,
+        },
+        position: { x: 0, y: 0, width: '100%', height: '100%' },
+      });
+    }
 
     // Subtle decorative accent line below title
     layers.push({
@@ -130,7 +163,9 @@ export function coverBlock(input: CoverBlockInput, context: TemplateContext): La
       id: 'cover-accent',
       content: {
         shape: 'rect',
-        fill: 'rgba(255, 255, 255, 0.2)',
+        fill: standardLightCover
+          ? withAlpha(theme.colors.primary, 0.24)
+          : 'rgba(255, 255, 255, 0.2)',
       },
       position: {
         x: '35%',
@@ -153,7 +188,7 @@ export function coverBlock(input: CoverBlockInput, context: TemplateContext): La
         fontWeight: 'bold',
         color: theme.colors.text,
         textAlign: 'center',
-        shadow: true,
+        shadow: !standardLightCover,
       },
     },
     position: {
@@ -176,7 +211,8 @@ export function coverBlock(input: CoverBlockInput, context: TemplateContext): La
         style: {
           fontSize: subtitleFontSize,
           fontFamily: getThemeFont(context, 'body'),
-          color: theme.colors.textMuted,
+          fontWeight: standardLightCover ? 'bold' : 'normal',
+          color: standardLightCover ? withAlpha(theme.colors.text, 0.78) : theme.colors.textMuted,
           textAlign: 'center',
           lineHeight: 1.5,
         },

package/src/doc/templates/diagramBlock.ts

@@ -17,7 +17,7 @@
 import type { Layer, ShapeLayer, TextLayer, PathLayer, MarkerStyle } from '../../schemas/Doc.js';
 import type { DiagramBlockInput, TemplateContext } from '../../schemas/BlockTemplates.js';
 import { resolveColorScheme, getThemeFont, themedFontSize } from '../utils/themeUtils.js';
-import { clipEndpoints, connectorPath, lineStyleDasharray } from '../utils/shapeGeometry.js';
+import { connectorPath, lineStyleDasharray, snapEndpoints } from '../utils/shapeGeometry.js';
 import { computeDiagramLayout, type DiagramNodePosition } from './diagramLayout.js';
 
 const NODE_WIDTH = 180;
@@ -124,7 +124,7 @@ export function diagramBlock(input: DiagramBlockInput, context: TemplateContext)
     const a = positions.get(edge.source);
     const b = positions.get(edge.target);
     if (!a || !b) continue;
-    const { start, end } = clipEndpoints(a, b);
+    const { start, end } = snapEndpoints(a, b);
     const pathLayer: PathLayer = {
       type: 'path',
       id: `edge-${edge.id}`,

package/src/doc/templates/drawingBlock.ts

@@ -18,7 +18,7 @@ import type { Layer, ShapeLayer, TextLayer, PathLayer } from '../../schemas/Doc.
 import type { DrawingBlockInput, TemplateContext } from '../../schemas/BlockTemplates.js';
 import { resolveColorScheme, getThemeFont, themedFontSize } from '../utils/themeUtils.js';
 import { computeDrawingLayout, type DrawingShape, type DrawingConnector } from './drawingLayout.js';
-import { shapePath, connectorPath, clipEndpoints } from '../utils/shapeGeometry.js';
+import { shapePath, connectorPath, snapEndpoints } from '../utils/shapeGeometry.js';
 
 const PADDING = 80;
 
@@ -102,7 +102,7 @@ export function drawingBlock(input: DrawingBlockInput, context: TemplateContext)
     const a = boxes.get(conn.from);
     const b = boxes.get(conn.to);
     if (!a || !b) continue;
-    const { start, end } = clipEndpoints(a, b);
+    const { start, end } = snapEndpoints(a, b);
     const path: PathLayer = {
       type: 'path',
       id: `connector-${conn.id}`,

package/src/doc/utils/shapeGeometry.ts

@@ -9,9 +9,11 @@
  *  - `markerPath(style, dir)` → the `<marker>` path for a line end-style, in the
  *    standard 0–10 marker viewBox (shared by the SSR `PathLayer` renderer and the
  *    editor's edge renderer).
- *  - `connectorPath(routing, start, end)` + `clipEndpoints(a, b)` → the line/edge
+ *  - `connectorPath(routing, start, end)` + `snapEndpoints(a, b)` → the line/edge
  *    geometry between two shapes (straight / orthogonal / curved), lifted from the
- *    diagram template so drawings and diagrams draw identical connectors.
+ *    diagram template so drawings and diagrams draw identical connectors. The older
+ *    `clipEndpoints(a, b)` helper remains for free-angle clipping, but rendered
+ *    connectors use snapped ports so authored lines land on stable attachment points.
  */
 
 import type { MarkerStyle } from '../../schemas/Doc.js';
@@ -411,6 +413,22 @@ export interface ClipBox {
   ry: number;
 }
 
+export type ConnectorPort =
+  | 'top'
+  | 'right'
+  | 'bottom'
+  | 'left'
+  | 'top-left'
+  | 'top-right'
+  | 'bottom-right'
+  | 'bottom-left';
+
+export interface ConnectorSnapPoint {
+  port: ConnectorPort;
+  x: number;
+  y: number;
+}
+
 /** Intersection of the center-to-center line with `from`'s bounding box. */
 export function clipPoint(from: ClipBox, to: ClipBox): { x: number; y: number } {
   const dx = to.cx - from.cx;
@@ -430,6 +448,76 @@ export function clipEndpoints(
   return { start: clipPoint(a, b), end: clipPoint(b, a) };
 }
 
+/** The stable connector ports exposed around a shape/card box. */
+export function snapPoints(box: ClipBox): ConnectorSnapPoint[] {
+  const left = box.cx - box.rx;
+  const right = box.cx + box.rx;
+  const top = box.cy - box.ry;
+  const bottom = box.cy + box.ry;
+  return [
+    { port: 'top', x: box.cx, y: top },
+    { port: 'right', x: right, y: box.cy },
+    { port: 'bottom', x: box.cx, y: bottom },
+    { port: 'left', x: left, y: box.cy },
+    { port: 'top-left', x: left, y: top },
+    { port: 'top-right', x: right, y: top },
+    { port: 'bottom-right', x: right, y: bottom },
+    { port: 'bottom-left', x: left, y: bottom },
+  ];
+}
+
+/** Nearest stable connector port on `box` to an arbitrary point. */
+export function nearestSnapPoint(
+  box: ClipBox,
+  point: { x: number; y: number },
+): ConnectorSnapPoint {
+  let best = snapPoints(box)[0];
+  let bestScore = Number.POSITIVE_INFINITY;
+  for (const candidate of snapPoints(box)) {
+    const score = distanceSq(candidate, point) + portTieBreak(candidate.port);
+    if (score < bestScore) {
+      best = candidate;
+      bestScore = score;
+    }
+  }
+  return best;
+}
+
+/**
+ * Pick the pair of connector ports, one on each box, with the shortest
+ * distance between them. This gives stable attachments to side/corner handles
+ * instead of arbitrary center-ray intersections.
+ */
+export function snapEndpoints(
+  a: ClipBox,
+  b: ClipBox,
+): { start: ConnectorSnapPoint; end: ConnectorSnapPoint } {
+  let bestStart = snapPoints(a)[0];
+  let bestEnd = snapPoints(b)[0];
+  let bestScore = Number.POSITIVE_INFINITY;
+  for (const start of snapPoints(a)) {
+    for (const end of snapPoints(b)) {
+      const score = distanceSq(start, end) + portTieBreak(start.port) + portTieBreak(end.port);
+      if (score < bestScore) {
+        bestStart = start;
+        bestEnd = end;
+        bestScore = score;
+      }
+    }
+  }
+  return { start: bestStart, end: bestEnd };
+}
+
+function distanceSq(a: { x: number; y: number }, b: { x: number; y: number }): number {
+  const dx = a.x - b.x;
+  const dy = a.y - b.y;
+  return dx * dx + dy * dy;
+}
+
+function portTieBreak(port: ConnectorPort): number {
+  return port.includes('-') ? 0.02 : 0;
+}
+
 /** Build the SVG `d` for a connector between two clipped endpoints. */
 export function connectorPath(
   routing: ConnectorRouting,