@bendyline/squisq 1.4.0 → 1.5.0

package/src/doc/validate.ts

@@ -0,0 +1,476 @@
+/**
+ * Markdown document validation.
+ *
+ * `validateMarkdownSource()` gives authors and agents fast, structural
+ * feedback on a squisq markdown document — the same checks the renderer
+ * applies, surfaced as diagnostics instead of degraded slides:
+ *
+ * - unknown template names (with a did-you-mean suggestion)
+ * - unknown drawing shapes, and shape annotations used outside a `{[drawing]}`
+ * - `{[…]}` text that was not recognized as an annotation (bad quoting,
+ *   non-heading placement, unknown inline icon)
+ * - malformed heading-attribute values (`x=abc`, bad `startTime`) and
+ *   non-numeric drawing-shape geometry
+ * - `connectsTo` / drawing `from`/`to` targets that don't resolve,
+ *   duplicate block ids, unparseable data fences (reported by `markdownToDoc`)
+ * - image references missing from the provided asset set (.dbk contents)
+ *
+ * The CLI exposes this as `squisq validate <input>`; agents can also call
+ * it directly and iterate until the diagnostics list is empty.
+ */
+
+import type { Doc, Block, DocDiagnostic } from '../schemas/Doc.js';
+import type {
+  MarkdownDocument,
+  MarkdownHeading,
+  MarkdownNode,
+  HtmlNode,
+} from '../markdown/types.js';
+import { parseMarkdown } from '../markdown/parse.js';
+import { getChildren, extractPlainText } from '../markdown/utils.js';
+import { coerceAnnotationValues } from '../markdown/annotationCoercion.js';
+import { markdownToDoc, flattenBlocks } from './markdownToDoc.js';
+import {
+  templateRegistry,
+  TEMPLATE_ALIASES,
+  resolveTemplateName,
+  isShapeName,
+  normalizeShapeKind,
+  SHAPE_NAMES,
+} from './templates/index.js';
+
+// ============================================
+// Options & result
+// ============================================
+
+export interface ValidateOptions {
+  /**
+   * Known asset paths for image/video reference checks — typically the
+   * file list of a .dbk container or the document's folder. Relative
+   * references not present here produce a `missing-asset` warning.
+   * When omitted, asset checks are skipped.
+   */
+  assets?: ReadonlySet<string> | ((path: string) => boolean);
+
+  /**
+   * Additional template names to accept beyond the built-in registry and
+   * the document's own `customTemplates` (e.g. app-registered templates).
+   */
+  extraTemplates?: readonly string[];
+}
+
+export interface MarkdownValidationResult {
+  /** All findings, in source order where line information exists. */
+  diagnostics: DocDiagnostic[];
+  errorCount: number;
+  warningCount: number;
+  /** The converted Doc (conversion diagnostics are included above). */
+  doc: Doc;
+}
+
+// ============================================
+// Entry points
+// ============================================
+
+/**
+ * Validate a squisq markdown source string. Parses, converts (collecting
+ * the conversion's own diagnostics), and runs the structural checks above.
+ */
+export function validateMarkdownSource(
+  source: string,
+  options?: ValidateOptions,
+): MarkdownValidationResult {
+  return validateMarkdownDoc(parseMarkdown(source), options);
+}
+
+/**
+ * Validate an already-parsed MarkdownDocument. See {@link validateMarkdownSource}.
+ */
+export function validateMarkdownDoc(
+  markdownDoc: MarkdownDocument,
+  options?: ValidateOptions,
+): MarkdownValidationResult {
+  const doc = markdownToDoc(markdownDoc);
+  const diagnostics: DocDiagnostic[] = [...(doc.diagnostics ?? [])];
+  const blocks = flattenBlocks(doc.blocks);
+
+  const knownTemplates = collectKnownTemplates(doc, options);
+
+  // Parent-aware walk: a `{[shape]}` annotation is only meaningful on the
+  // direct child of a `{[drawing]}` block, so the template check needs each
+  // block's parent. Drawing connectors are validated against their siblings.
+  const visit = (block: Block, parent: Block | undefined): void => {
+    checkTemplate(block, parent, knownTemplates, diagnostics);
+    checkAttributeCoercion(block, parent, diagnostics);
+    if (isDrawingBlock(block)) checkDrawingConnectors(block, diagnostics);
+    for (const child of block.children ?? []) visit(child, block);
+  };
+  for (const block of doc.blocks) visit(block, undefined);
+
+  checkUnrecognizedAnnotations(markdownDoc, diagnostics);
+
+  if (options?.assets) {
+    const hasAsset = normalizeAssetCheck(options.assets);
+    checkAssets(markdownDoc, blocks, hasAsset, diagnostics);
+  }
+
+  diagnostics.sort(
+    (a, b) => (a.line ?? Number.MAX_SAFE_INTEGER) - (b.line ?? Number.MAX_SAFE_INTEGER),
+  );
+
+  return {
+    diagnostics,
+    errorCount: diagnostics.filter((d) => d.severity === 'error').length,
+    warningCount: diagnostics.filter((d) => d.severity === 'warning').length,
+    doc,
+  };
+}
+
+// ============================================
+// Template checks
+// ============================================
+
+function collectKnownTemplates(doc: Doc, options?: ValidateOptions): Set<string> {
+  return new Set<string>([
+    ...Object.keys(templateRegistry),
+    ...Object.keys(TEMPLATE_ALIASES),
+    ...(doc.customTemplates?.map((t) => t.name) ?? []),
+    ...(options?.extraTemplates ?? []),
+  ]);
+}
+
+/** True when `block` is a `{[drawing]}` container (after alias resolution). */
+function isDrawingBlock(block: Block): boolean {
+  return resolveTemplateName(block.template ?? '') === 'drawing';
+}
+
+function checkTemplate(
+  block: Block,
+  parent: Block | undefined,
+  known: Set<string>,
+  diagnostics: DocDiagnostic[],
+): void {
+  const requested = block.sourceHeading?.templateAnnotation?.template;
+  if (!requested) return;
+
+  // Inside a drawing, the annotation names a shape primitive, not a template.
+  if (parent && isDrawingBlock(parent)) {
+    if (isShapeName(requested)) return;
+    const suggestion = nearestName(requested, new Set(SHAPE_NAMES));
+    diagnostics.push({
+      severity: 'warning',
+      code: 'unknown-shape',
+      message:
+        `Unknown shape "${requested}" in drawing — the child will be skipped` +
+        (suggestion ? `. Did you mean "${suggestion}"?` : ''),
+      blockId: block.id,
+      ...lineOf(block),
+    });
+    return;
+  }
+
+  // A shape annotation outside a drawing has no parent to interpret it.
+  if (isShapeName(requested)) {
+    diagnostics.push({
+      severity: 'warning',
+      code: 'shape-outside-drawing',
+      message: `Shape "${requested}" is only recognized on a child heading of a {[drawing]} block`,
+      blockId: block.id,
+      ...lineOf(block),
+    });
+    return;
+  }
+
+  if (known.has(requested) || known.has(resolveTemplateName(requested))) return;
+
+  const suggestion = nearestName(requested, known);
+  diagnostics.push({
+    severity: 'warning',
+    code: 'unknown-template',
+    message:
+      `Unknown template "${requested}" — the block will render as a plain fallback card` +
+      (suggestion ? `. Did you mean "${suggestion}"?` : ''),
+    blockId: block.id,
+    ...lineOf(block),
+  });
+}
+
+/** Numeric geometry keys carried in a shape's `{[…]}` params. */
+const NUMERIC_SHAPE_KEYS = ['x', 'y', 'width', 'height', 'w', 'h', 'strokeWidth', 'borderRadius'];
+
+/** Re-run heading-attribute coercion to surface its warnings with context. */
+function checkAttributeCoercion(
+  block: Block,
+  parent: Block | undefined,
+  diagnostics: DocDiagnostic[],
+): void {
+  // Pandoc `{#id key=value}` params (x/y/connectsTo/startTime/duration).
+  const params = block.sourceHeading?.attributes?.params;
+  if (params) {
+    const { warnings } = coerceAnnotationValues(params);
+    for (const warning of warnings) {
+      diagnostics.push({
+        severity: 'warning',
+        code: 'invalid-attribute',
+        message: `Block "${block.id}": ${warning}`,
+        blockId: block.id,
+        ...lineOf(block),
+      });
+    }
+  }
+
+  // A drawing shape's geometry lives in its `{[shape …]}` params
+  // (templateOverrides), not the Pandoc block — validate those numerics too.
+  if (parent && isDrawingBlock(parent) && isShapeName(block.template)) {
+    const overrides = block.templateOverrides ?? {};
+    for (const key of NUMERIC_SHAPE_KEYS) {
+      const raw = overrides[key];
+      if (raw == null) continue;
+      const value = raw.replace(/,\s*$/, '').trim();
+      if (value !== '' && !Number.isFinite(Number(value))) {
+        diagnostics.push({
+          severity: 'warning',
+          code: 'invalid-attribute',
+          message: `Drawing shape "${block.id}": "${key}" is not a number (${JSON.stringify(raw)})`,
+          blockId: block.id,
+          ...lineOf(block),
+        });
+      }
+    }
+  }
+}
+
+/**
+ * A drawing's `line`/`arrow` connectors reference sibling shapes by id via
+ * `from`/`to`; flag any that don't resolve (mirrors the `connectsTo`
+ * unresolved-connection check, but for the `{[…]}` param form).
+ */
+function checkDrawingConnectors(block: Block, diagnostics: DocDiagnostic[]): void {
+  const children = block.children ?? [];
+  const ids = new Set(children.map((c) => c.id));
+  for (const child of children) {
+    const kind = normalizeShapeKind(child.sourceHeading?.templateAnnotation?.template);
+    if (kind !== 'line' && kind !== 'arrow') continue;
+    const overrides = child.templateOverrides ?? {};
+    for (const key of ['from', 'to'] as const) {
+      const raw = overrides[key];
+      if (raw == null) continue;
+      const ref = raw.replace(/,\s*$/, '').trim();
+      if (ref && !ids.has(ref)) {
+        diagnostics.push({
+          severity: 'warning',
+          code: 'unresolved-connection',
+          message: `Drawing connector "${child.id}" references unknown ${key} "${ref}"`,
+          blockId: child.id,
+          ...lineOf(child),
+        });
+      }
+    }
+  }
+}
+
+// ============================================
+// Unrecognized `{[…]}` text
+// ============================================
+
+const ANNOTATION_LIKE_RE = /\{\[/;
+
+/**
+ * Flag literal `{[` text that survived parsing. On a heading this usually
+ * means broken quoting; in body content it usually means the author
+ * expected list-item/paragraph annotations, which only headings support
+ * (or referenced an unknown inline icon).
+ */
+function checkUnrecognizedAnnotations(
+  markdownDoc: MarkdownDocument,
+  diagnostics: DocDiagnostic[],
+): void {
+  const walk = (node: MarkdownNode, headingLine: number | undefined): void => {
+    if (node.type === 'heading') {
+      const heading = node as MarkdownHeading;
+      const text = extractPlainText(heading);
+      if (ANNOTATION_LIKE_RE.test(text)) {
+        diagnostics.push({
+          severity: 'warning',
+          code: 'unparsed-annotation',
+          message:
+            `Heading "${truncate(text)}" contains "{[…]}" text that was not recognized — ` +
+            `check the quoting, or whether the token is a known inline icon`,
+          ...(heading.position ? { line: heading.position.start.line } : {}),
+        });
+      }
+      return; // heading inline children already covered by extractPlainText
+    }
+    if (node.type === 'text' && ANNOTATION_LIKE_RE.test(node.value)) {
+      diagnostics.push({
+        severity: 'warning',
+        code: 'unparsed-annotation',
+        message:
+          `Body text contains "{[…]}" — template annotations are only recognized on ` +
+          `headings (or the token is not a known inline icon)`,
+        ...(node.position
+          ? { line: node.position.start.line }
+          : headingLine != null
+            ? { line: headingLine }
+            : {}),
+      });
+      return;
+    }
+    if (node.type === 'code') return; // code blocks legitimately contain {[
+    for (const child of getChildren(node)) {
+      walk(child, headingLine);
+    }
+  };
+
+  for (const child of markdownDoc.children) {
+    walk(child, child.position?.start.line);
+  }
+}
+
+// ============================================
+// Asset checks
+// ============================================
+
+function normalizeAssetCheck(
+  assets: ReadonlySet<string> | ((path: string) => boolean),
+): (path: string) => boolean {
+  if (typeof assets === 'function') return assets;
+  return (path: string) => assets.has(path) || assets.has(path.replace(/^\.\//, ''));
+}
+
+const URL_SCHEME_RE = /^[a-z][a-z0-9+.-]*:/i;
+
+/** A reference that should resolve inside the bundle: relative, no scheme. */
+function isBundleRelative(url: string): boolean {
+  return (
+    url.length > 0 && !URL_SCHEME_RE.test(url) && !url.startsWith('//') && !url.startsWith('#')
+  );
+}
+
+/** Template param keys whose values reference media assets. */
+const ASSET_PARAM_KEYS = ['src', 'imageSrc', 'videoSrc', 'poster', 'backgroundImage'];
+
+function checkAssets(
+  markdownDoc: MarkdownDocument,
+  blocks: Block[],
+  hasAsset: (path: string) => boolean,
+  diagnostics: DocDiagnostic[],
+): void {
+  const report = (url: string, line?: number, blockId?: string) => {
+    if (!isBundleRelative(url) || hasAsset(url)) return;
+    diagnostics.push({
+      severity: 'warning',
+      code: 'missing-asset',
+      message: `Referenced asset "${url}" was not found in the bundle`,
+      ...(blockId ? { blockId } : {}),
+      ...(line != null ? { line } : {}),
+    });
+  };
+
+  // Markdown image nodes + raw-HTML <img src>.
+  const walk = (node: MarkdownNode): void => {
+    if (node.type === 'image') {
+      report(node.url, node.position?.start.line);
+    }
+    if (node.type === 'htmlBlock' || node.type === 'htmlInline') {
+      walkHtmlImages(node.htmlChildren, (src) => report(src, node.position?.start.line));
+    }
+    for (const child of getChildren(node)) walk(child);
+  };
+  for (const child of markdownDoc.children) walk(child);
+
+  // Media references in template params / structured data.
+  for (const block of blocks) {
+    const sources: Array<Record<string, unknown> | undefined> = [
+      block.templateOverrides,
+      block.templateData,
+    ];
+    for (const source of sources) {
+      if (!source) continue;
+      for (const key of ASSET_PARAM_KEYS) {
+        const value = source[key];
+        if (typeof value === 'string') {
+          report(value, block.sourceHeading?.position?.start.line, block.id);
+        }
+      }
+      const images = source['images'];
+      const list =
+        typeof images === 'string'
+          ? images.split(',').map((s) => s.trim())
+          : Array.isArray(images)
+            ? images.filter((i): i is string => typeof i === 'string')
+            : [];
+      for (const img of list) {
+        report(img, block.sourceHeading?.position?.start.line, block.id);
+      }
+    }
+  }
+}
+
+function walkHtmlImages(nodes: HtmlNode[], report: (src: string) => void): void {
+  for (const node of nodes) {
+    if (node.type !== 'htmlElement') continue;
+    if (node.tagName === 'img' && node.attributes.src) {
+      report(node.attributes.src);
+    }
+    walkHtmlImages(node.children, report);
+  }
+}
+
+// ============================================
+// Did-you-mean
+// ============================================
+
+/**
+ * Nearest known name by edit distance. Returns undefined when nothing is
+ * plausibly close (distance > 2 and > 40% of the input length).
+ */
+function nearestName(input: string, candidates: Set<string>): string | undefined {
+  let best: string | undefined;
+  let bestDist = Infinity;
+  const lower = input.toLowerCase();
+  for (const candidate of candidates) {
+    const dist = levenshtein(lower, candidate.toLowerCase());
+    if (dist < bestDist) {
+      bestDist = dist;
+      best = candidate;
+    }
+  }
+  if (best && (bestDist <= 2 || bestDist <= Math.ceil(input.length * 0.4))) {
+    return resolveTemplateName(best);
+  }
+  return undefined;
+}
+
+function levenshtein(a: string, b: string): number {
+  if (a === b) return 0;
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  let prev = new Array<number>(n + 1);
+  let curr = new Array<number>(n + 1);
+  for (let j = 0; j <= n; j++) prev[j] = j;
+  for (let i = 1; i <= m; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[n];
+}
+
+// ============================================
+// Helpers
+// ============================================
+
+function lineOf(block: Block): { line: number } | Record<string, never> {
+  const line = block.sourceHeading?.position?.start.line;
+  return line != null ? { line } : {};
+}
+
+function truncate(text: string, max = 40): string {
+  return text.length <= max ? text : `${text.slice(0, max)}…`;
+}

package/src/generate/slideshowGenerator.ts

@@ -89,6 +89,13 @@ const DEFAULT_ACCENT_POSITIONS: AccentPosition[] = ['left-strip', 'right-strip',
 /**
  * Generate a slideshow `Doc` from text and optional images.
  *
+ * @deprecated Prefer the transform pipeline: convert content with
+ * `markdownToDoc` (content-aware auto templates are on by default) and
+ * shape it with `applyTransform` from `@bendyline/squisq/transform` —
+ * one engine for text→slides, with styles, theme pairing, pacing, and a
+ * duration budget (`TransformStyleConfig.budget`). This standalone
+ * generator is kept for API stability but no longer gains features.
+ *
  * ```ts
  * const doc = generateSlideshow(articleText, myImages, {
  *   title: 'Mount Rainier',

package/src/icons/index.ts

@@ -16,3 +16,11 @@ export {
   iconGlyph,
 } from './resolve.js';
 export type { IconSuggestion } from './resolve.js';
+export {
+  iconMarker,
+  hasIconMarker,
+  stripIconMarkers,
+  splitIconMarkers,
+  iconClass,
+} from './inlineIconMarker.js';
+export type { IconTextRun } from './inlineIconMarker.js';

package/src/icons/inlineIconMarker.ts

@@ -0,0 +1,73 @@
+/**
+ * Inline-icon markers for template text.
+ *
+ * Slide templates flatten rich markdown body content into strings before
+ * rendering. Inline icons need to survive that flattening step, so we encode
+ * them as sentinel-delimited text markers and let `TextLayer` turn them back
+ * into FontAwesome glyphs when rendering.
+ */
+
+import type { IconFamily } from './iconData.js';
+
+/**
+ * Private-Use-Area sentinel that brackets an encoded icon.
+ * Kept as an escape sequence so the source remains valid TypeScript text.
+ */
+const SENTINEL = '\uE000';
+
+/** Matches one encoded marker: `<sentinel><family>:<name><sentinel>`. */
+const MARKER_RE = new RegExp(`${SENTINEL}([a-z]+):([a-zA-Z0-9-]+)${SENTINEL}`, 'g');
+
+/** Encode a resolved icon (family + name) as an embeddable text marker. */
+export function iconMarker(family: IconFamily, name: string): string {
+  return `${SENTINEL}${family}:${name}${SENTINEL}`;
+}
+
+/** True when a string contains at least one encoded icon marker. */
+export function hasIconMarker(value: string): boolean {
+  return value.includes(SENTINEL);
+}
+
+/** Remove every icon marker, leaving a clean plain-text projection. */
+export function stripIconMarkers(value: string): string {
+  return value.replace(MARKER_RE, '');
+}
+
+/** A run of a marker-bearing string: literal text or a resolved icon. */
+export type IconTextRun =
+  | { type: 'text'; text: string }
+  | { type: 'icon'; family: IconFamily; name: string };
+
+/**
+ * Split a string into ordered text/icon runs. Text between markers is
+ * preserved verbatim, including whitespace; each marker becomes an icon run.
+ */
+export function splitIconMarkers(value: string): IconTextRun[] {
+  const runs: IconTextRun[] = [];
+  let lastIndex = 0;
+  MARKER_RE.lastIndex = 0;
+
+  let match: RegExpExecArray | null;
+  while ((match = MARKER_RE.exec(value)) !== null) {
+    if (match.index > lastIndex) {
+      runs.push({ type: 'text', text: value.slice(lastIndex, match.index) });
+    }
+    runs.push({
+      type: 'icon',
+      family: match[1] as IconFamily,
+      name: match[2],
+    });
+    lastIndex = match.index + match[0].length;
+  }
+
+  if (lastIndex < value.length) {
+    runs.push({ type: 'text', text: value.slice(lastIndex) });
+  }
+
+  return runs;
+}
+
+/** FontAwesome CSS class for a resolved icon, e.g. `fa-solid fa-rocket`. */
+export function iconClass(family: IconFamily, name: string): string {
+  return `fa-${family} fa-${name}`;
+}

package/src/imageEdit/export.ts

@@ -15,7 +15,8 @@
 
 import type { ContentContainer } from '../storage/ContentContainer.js';
 import type { ImageEditCanvas, ImageEditDoc, ImageEditLayer } from '../schemas/ImageEditDoc.js';
-import type { Position } from '../schemas/Doc.js';
+import type { MarkerStyle, Position } from '../schemas/Doc.js';
+import { markerPath, shapePath } from '../doc/utils/shapeGeometry.js';
 
 /** Supported export formats. */
 export type ImageEditExportFormat = 'png' | 'jpeg' | 'webp';
@@ -78,7 +79,15 @@ export async function exportImageEditDoc(
 // SVG construction
 // ============================================
 
-async function buildSvgString(doc: ImageEditDoc, container: ContentContainer): Promise<string> {
+/**
+ * Build the standalone SVG string that mirrors the canvas + layers. Exposed
+ * for tests (the raster step needs a browser); shape/text/path layers don't
+ * touch `container`, only image layers do (to inline asset bytes).
+ */
+export async function buildSvgString(
+  doc: ImageEditDoc,
+  container: ContentContainer,
+): Promise<string> {
   const { width, height, background } = doc.canvas;
   const bgRect =
     background && background !== 'transparent'
@@ -145,6 +154,10 @@ async function renderLayerInner(
     return `<line x1="${x}" y1="${y}" x2="${x + w}" y2="${y + h}"${stroke}${strokeWidth}/>`;
   }
 
+  if (layer.type === 'path') {
+    return renderPathToSvg(layer, x, y, w, h);
+  }
+
   // text
   const c = layer.content;
   const style = c.style;
@@ -169,6 +182,76 @@ async function renderLayerInner(
   );
 }
 
+/**
+ * Serialize a `path` layer to SVG. Mirrors the runtime
+ * `react/src/layers/PathLayer.tsx`: when `shapeKind` is set, `d` is
+ * re-derived from the position box via `shapePath` (so named shapes scale);
+ * otherwise the stored absolute `d` is used. Start/end markers are emitted
+ * as `<marker>` defs scoped to the layer id, matching `markerPath` geometry.
+ */
+function renderPathToSvg(
+  layer: ImageEditLayer & { type: 'path' },
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+): string {
+  const c = layer.content;
+  const d = c.shapeKind ? (shapePath(c.shapeKind, x, y, w, h) ?? c.d) : c.d;
+  const stroke = c.stroke ?? '#1e293b';
+  const strokeWidth = c.strokeWidth ?? 2;
+  const fill = c.fill ?? 'none';
+  const dash = c.dasharray ? ` stroke-dasharray="${escapeAttr(c.dasharray)}"` : '';
+
+  // Markers: explicit start/end win; otherwise derive from the legacy `arrow` flag.
+  const startStyle = effectiveExportMarker(c.startMarker, c.arrow, 'start');
+  const endStyle = effectiveExportMarker(c.endMarker, c.arrow, 'end');
+  const start = markerPath(startStyle, 'start');
+  const end = markerPath(endStyle, 'end');
+  const startId = `marker-start-${layer.id}`;
+  const endId = `marker-end-${layer.id}`;
+  const defs =
+    start || end
+      ? `<defs>${start ? markerDefSvg(startId, 'start', start, stroke) : ''}${
+          end ? markerDefSvg(endId, 'end', end, stroke) : ''
+        }</defs>`
+      : '';
+  const markerStart = start ? ` marker-start="url(#${startId})"` : '';
+  const markerEnd = end ? ` marker-end="url(#${endId})"` : '';
+
+  return (
+    defs +
+    `<path d="${escapeAttr(d)}" fill="${escapeAttr(fill)}"` +
+    ` stroke="${escapeAttr(stroke)}" stroke-width="${strokeWidth}"${dash}${markerStart}${markerEnd}/>`
+  );
+}
+
+function effectiveExportMarker(
+  explicit: MarkerStyle | undefined,
+  arrow: (ImageEditLayer & { type: 'path' })['content']['arrow'],
+  end: 'start' | 'end',
+): MarkerStyle {
+  if (explicit) return explicit;
+  return arrow === 'both' || arrow === end ? 'arrow' : 'none';
+}
+
+function markerDefSvg(
+  id: string,
+  dir: 'start' | 'end',
+  marker: { d: string; filled: boolean },
+  stroke: string,
+): string {
+  const refX = dir === 'end' ? 9 : 1;
+  const paint = marker.filled
+    ? `fill="${escapeAttr(stroke)}"`
+    : `fill="none" stroke="${escapeAttr(stroke)}" stroke-width="1.5"`;
+  return (
+    `<marker id="${escapeAttr(id)}" viewBox="0 0 10 10" refX="${refX}" refY="5"` +
+    ` markerWidth="4" markerHeight="4" orient="auto-start-reverse" markerUnits="strokeWidth">` +
+    `<path d="${escapeAttr(marker.d)}" ${paint}/></marker>`
+  );
+}
+
 function preserveAspectRatioFor(fit?: 'cover' | 'contain' | 'fill'): string {
   if (fit === 'cover') return 'xMidYMid slice';
   if (fit === 'fill') return 'none';

package/src/imageEdit/index.ts

@@ -66,6 +66,7 @@ export {
 // Export
 export {
   exportImageEditDoc,
+  buildSvgString,
   type ImageEditExportFormat,
   type ImageEditExportOptions,
 } from './export.js';